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Intended  Audience 

This  manual  provides  reference  information  on  all  BASIC-PLUS-2  com¬ 
mands,  directives,  statements,  and  functions.  Readers  are  presumed  to 
have  some  previous  knowledge  of  BASIC  or  another  high-level  program¬ 
ming  language.  This  manual  should  be  used  with  the  other  manual  in  the 
documentation  set. 


Operating  Systems  and  Versions 

BASIC-PLUS-2  runs  on  the  following  operating  systems  and  versions: 

RSX-llM  Version  4.2  or  higher 
RSX-llM-PLUS  Version  3.0  or  higher 
Micro/RSX  Version  3.0  or  higher 
RSTS/E  Version  9.2  or  higher 
Micro/RSTS  Version  2.1  or  higher 
P/OS  Version  3.1  or  higher 


Associated  Documents 

This  manual  is  one  of  two  manuals  that  form  the  BASIC-PLUS-2  docu¬ 
mentation  set.  The  other  manual  in  the  documentation  set,  the 
BASIC-PLUS~2  User's  Guide,  contains  tutorial  material  on  developing 
BASIC-PLUS-2  programs,  describes  BASIC-PLUS-2  programming  con¬ 
cepts,  and  also  provides  information  on  advanced  programming  techniques 
and  ways  to  optimize  your  program  development.  If  you  are  unfamiliar 
with  a  topic,  you  may  want  to  read  the  information  in  the  BASIC-PLUS~2 
User's  Guide  before  consulting  this  manual. 
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If  you  are  an  inexperienced  BASIC  programmer,  you  should  read  the 
following  manuals  before  using  the  BASIC-PLUS-2  document  set: 

•  Introduction  to  BASIC 

•  BASIC  for  Beginners 

•  More  BASIC  for  Beginners 


Structure  of  This  Document 


This  manual  consists  of  four  chapters  and  four  appendixes. 


Chapter  1 
Chapter  2 
Chapter  3 
Chapter  4 
Appendix  A 
Appendix  B 
Appendix  C 
Appendix  D 


Summarizes  BASIC-PLUS-2  program  elements  and  structure 

Describes  BASIC-PLUS-2  environment  commands 

Describes  BASIC-PLUS-2  compiler  directives 

Describes  BASIC-PLUS-2  statements  and  functions 

Lists  the  BASIC-PLUS-2  keywords 

Describes  BASIC-PLUS-2  debugger  commands 

Describes  BASIC-PLUS-2  editing  mode  commands 

Lists  and  describes  the  Object  Time  System  (OTS)  routines 


Chapters  2,  3,  and  4,  and  Appendixes  B  and  C  provide  reference  material 
on  each  BASIC-PLUS-2  language  element.  The  language  elements  are 
arranged  in  alphabetical  order  within  each  chapter  or  appendix,  and 
each  language  element  begins  on  a  separate  page.  The  language  element 
descriptions  contain  the  following  information: 

Overview  An  overview  of  what  the  statement  or  command  does. 

Format  The  required  syntax  for  the  language  element. 

Syntax  Rules  Any  rules  governing  the  use  of  parameters,  separators,  or 
other  syntax  items,  effect  of  the  statement  or  command  on 
program  execution,  and  any  restrictions  governing  its  use. 


Example  One  or  more  examples  of  the  statement  in  a  partial  program. 

Where  appropriate,  explanatory  text  and  program  output  are 
included. 
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Please  use  the  Reader's  Comments  form  in  the  back  of  this  book  to  report 
documentation  errors,  to  comment  on  how  information  is  presented,  or  to 
provide  suggestions  for  future  publications. 


Conventions  Used  in  This  Document 


This  manual  uses  case  of  text,  symbols,  and  mnemonics  in  syntactical 
diagrams.  This  symbology  aids  in  providing  more  concise  and  exact 
descriptions  of  syntactic  variables,  rules,  and  format. 


Convention 

Meaning 

$  BASIC 

In  command  examples,  the  user's  response  to  a  system 
prompt  is  printed  in  red;  system  prompts  are  printed 
in  black. 

UPPERCASE  letters 

Uppercase  letters  are  used  for  BASIC-PLUS-2  key¬ 
words  and  must  be  coded  exactly  as  shown. 

lowercase  letters 

Lowercase  letters  are  used  to  indicate  user-supplied 
names  or  characters. 

(1 

Brackets  enclose  an  optional  portion  of  a  format. 
Brackets  around  vertically  stacked  items  indicate  that 
you  can  select  one  of  the  enclosed  items.  You  must 
include  all  punctuation  as  it  appears  in  the  brackets. 

0 

Braces  enclose  a  mandatory  portion  of  a  format.  Braces 
around  vertically  stacked  items  indicate  that  you  must 
choose  one  of  the  enclosed  items.  You  must  include 
all  punctuation  as  it  appears  in  the  braces. 

A  vertical  ellipsis  indicates  that  code,  which  would 
normally  be  present,  is  not  shown. 

An  ellipsis  indicates  that  the  immediately  preceding 
item  can  be  repeated.  An  ellipsis  following  a  format 
unit  enclosed  in  brackets  or  braces  means  that  you  can 
repeat  the  entire  unit.  If  repeated  items  or  format  units 
must  be  separated  by  commas,  the  ellipsis  is  preceded 
by  a  comma  (,...). 

The  following  mnemonics  are  used  in  the  syntax  diagrams: 


Mnemonic 

angle 

array 

chnl-exp 

com 

cond 

const 

data-type 

def 

exp 

file-spec 

func 

int 

int-exp 

int-var 

label 

lex 

line 

line-num 

lit 

log-exp 

map 

matrix 

name 

num 

param-list 


Meaning 

An  angle  in  radians 

An  array;  syntax  rules  specify  whether  the  bounds  or  dimen¬ 
sions  can  be  specified 

An  I/O  channel  associated  with  a  file 
Specific  to  a  COMMON  block 

Conditional  expression;  indicates  that  an  expression  can  be 
either  logical  or  relational 

A  constant  value 
A  data  type  keyword 
Specific  to  a  DEF  function 
An  expression 
A  file  specification 

Specific  to  a  FUNCTION  subprogram 
An  integer  value 

An  expression  that  represents  an  integer  value 
A  variable  that  contains  an  integer  value 
An  alphanumeric  statement  label 

Lexical;  used  to  indicate  a  component  of  a  compiler  directive 

A  statement  line;  may  or  may  not  be  numbered 

A  statement  line  number 

A  literal  value,  in  quotation  marks 

Logical  expression 

Specific  to  a  MAP  statement 

A  two-dimensional  array 

A  name  or  identifier;  indicates  the  declaration  of  a  name 
or  the  name  of  a  BASIC-PLUS-2  structure,  such  as  a  SUB 
subprogram 

A  numeric  value 

A  parameter  list,  such  as  for  a  SUB  subprogram 


Mnemonic 

Meaning 

pass-mech 

real 

rel-exp 

str 

A  valid  BASIC-PLUS-2  passing  mechanism 

A  floating-point  value 

Relational  expression 

A  character  string 

str-exp 

str-var 

sub 

An  expression  that  represents  a  character  string 

A  variable  that  contains  a  character  string 

Specific  to  a  SUB  subprogram 

target 

The  target  point  of  a  branch  statement;  either  a  line  number 
or  a  label 

unsubs-var 

Unsubscripted  variable,  as  opposed  to  an  array  element 

var 

A  variable 

Summary  of  New  and  Changed  Features 
for  Version  2.4 


The  following  is  a  list  of  the  major  changes  for  Version  2.4  of 

BASIC-PLUS-2: 

•  The  DCL  command  BASIC  now  allows  you  to  compile  BASIC-PLUS-2 
programs  from  DCL  level.  New  qualifiers  to  this  command  have  also 
been  added. 

•  The  new  Optimizer  Utility  is  useful  for  large  tasks  as  it  reduces  the 
size  of  your  task  by  replacing  common  OTS  calls  with  subroutines. 
See  the  BASlC-PLUS-2  User's  Guide  for  a  complete  description  of  the 
Optimizer  Utility. 

•  The  dollar  sign  ( $ )  suffix  for  strings  and  percent  sign  ( % )  suffix  for 
integers  are  allowed  on  explicitly  declared  variables  and  constants. 

•  The  new  PROGRAM  statement  allows  you  to  optionally  name  a  main 
program  unit.  This  name  becomes  the  module  name  of  the  compiled 
source. 

•  You  can  return  a  function  value  exiting  with  the  following  statements: 

-  END/EXIT  FUNCTION 

-  END/EXIT  DEF 

•  New  functions  MAX  and  MIN  are  provided  for  the  comparison  of  a 
series  of  arguments. 

•  The  new  MOD  function  divides  one  numeric  argument  by  another 
and  returns  the  remainder. 

•  The  new  compiler  directive  %PRINT  allows  you  to  print  a  message 
during  the  compilation  of  a  source  program  without  aborting  the 
compilation. 

•  The  new  CAUSE  ERROR  statement  allows  you  to  generate  a 
BASIC-PLUS-2  run-time  error  and  transfer  control  to  a 
BASIC-PLUS-2  error  handler. 

•  The  new  SET  [NO]  PROMPT  statement  allows  you  to  choose  whether 
a  question  mark  prompt  appears  after  BASIC-PLUS-2  executes  an 
INPUT,  LINPUT,  INPUT  LINE,  MAT  INPUT,  or  MAT  LINPUT 
statement  on  channel  #0. 
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The  new  EXTRACT  command  allows  you  to  extract  program  lines 
from  a  program. 

The  XLATE$  function  has  been  added  as  a  synonym  to  the  XLATE 
function. 

The  following  new  extension  to  the  OPTION  statement  has  been 
added: 

OPTION  CONSTANT  TYPE  -  data-type 

Extensions  to  the  REMAP  and  MAP  DYNAMIC  statements  allow  you 
to  redefine  the  storage  allocated  to  a  previously  declared  static  string 
variable. 

The  BASlC-PLUS-2  compiler  now  recognizes  RSX  logical  names  in  file 
specifications. 

DEE,  DEE*,  EXTERNAL,  EUNCTION,  and  SUB  statements  now  accept 
up  to  32  parameters.  MACRO- 11  subprograms  still  accept  a  maximum 
of  255  parameters. 

The  BASlC-PLUS-2  compiler  signals  a  warning  message  if  it  encoun¬ 
ters  a  loop  that  will  not  execute  or  if  a  loop  variable  exceeds  the 
allowable  range  for  its  datatype. 

The  BASlC-PLUS-2  compiler  signals  a  warning  message  if  you  specify 
a  VAX  BASIC  reserved  keyword  in  your  program.  The  VAX  BASIC 
reserved  keywords  are  listed  in  Appendix  A  of  this  manual. 

PRINT  USING  format  errors  are  now  trappable  errors. 

The  compiler  listing  now  contains  page  numbers. 

BASlC-PLUS-2  signals  errors  that  occur  when  duplicate  or  non¬ 
ascending  line  numbers  are  contained  in  programs  appended  with  the 
APPEND  command  or  read  into  memory  with  the  OLD  command. 
See  the  BASIC-PLUS-2  User's  Guide  for  a  list  of  all  compile-time  and 
run-time  error  messages. 

You  can  now  specify  binary,  octal,  hexadecimal,  or  RAD-50  radix 
literal  specifiers.  This  increases  compatiblity  with  other  DIGITAL 
BASICS. 

Online  help  has  been  improved. 


Chapter  1 

Program  Elements  and  Structure 


The  building  blocks  of  a  BASlC-PLUS-2  program  are  as  follows: 

•  Program  lines  and  their  components 

•  The  BASlC-PLUS-2  character  set 

•  BASlC-PLUS-2  data  types 

•  Variables  and  constants 

•  Expressions 

•  Program  documentation 

These  building  blocks  are  described  in  the  following  sections. 


1 . 1  Components  of  Program  Lines 

A  BASIC-PLUS-2  program  is  a  series  of  program  lines  that  contain  instruc¬ 
tions  for  the  BASIC-PLUS-2  compiler.  These  instructions  are  in  the  form 
of  statements  that  contain  keywords,  operators,  and  operands. 

All  BASIC-PLUS-2  program  lines  can  contain  the  following: 

•  Line  numbers  or  labels 

•  Statements  and  functions 

•  Compiler  directives 

•  Comments 

•  A  line  terminator  (carriage  return) 

These  components  are  discussed  in  the  following  sections. 
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1.1.1  Line  Numbers 


Every  BASIC-PLUS-2  statement  must  be  associated  with  a  line  number. 
Thus,  the  first  element  in  a  BASIC-PLUS-2  program  must  be  a  line  num¬ 
ber.  A  line  number  must  be  an  integer  from  1  through  32767  terminated 
by  a  space  or  a  tab.  BASIC-PLUS-2  ignores  leading  spaces,  tabs,  and 
zeros  in  line  numbers.  Embedded  spaces,  tabs,  and  commas  within  line 
numbers  cause  BASIC-PLUS-2  to  signal  an  error. 

A  line  number  followed  by  a  carriage  return  does  not  constitute  a 
BASIC-PLUS-2  program  line.  A  program  line  must  contain  a  statement  or 
a  comment  field.  Comment  fields  are  discussed  in  Section  1. 1.5.1.  A  new 
line  number  or  a  carriage  return  terminates  a  BASIC-PLUS-2  program  line. 

A  program  line  can  contain  any  number  of  text  lines;  however,  a  text  line 
cannot  exceed  255  characters  on  RSTS/E  systems,  and  132  characters  on 
RSX  systems. 

BASIC-PLUS-2  uses  line  numbers  to  do  the  following: 

•  Indicate  the  order  of  statement  execution 

•  Provide  control  points  for  branching 

•  Help  in  debugging  and  updating  programs 

•  Find  the  location  of  run-time  errors 

•  Resume  processing  after  an  error  has  been  handled 

Each  BASIC-PLUS-2  line  number  must  be  unique.  BASIC-PLUS-2  ignores 
leading  spaces,  tabs,  and  zeros  in  line  numbers. 


1.1.2  Labels 


A  label  is  a  1-  to  31 -character  name  that  identifies  a  statement  or  block  of 
statements.  It  may  immediately  follow  a  line  number.  The  label  logically 
identifies  a  statement  or  block  of  statements.  The  label  name  must  begin 
with  a  letter;  the  remaining  characters,  if  any,  can  be  any  combination  of 
letters,  digits,  dollar  signs  ( $ ),  underscores  ( _ ),  or  periods  ( . ). 

A  label  name  must  be  separated  from  the  statement  it  identifies  with  a 
colon  ( : ).  For  example: 

100  Yes.routine:  PRINT  "Your  answer  is  YES." 
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The  colon  is  not  part  of  the  label  name.  It  informs  BASIC-PLUS-2  that  the 
label  is  being  defined  rather  than  referenced.  Consequently,  the  colon  is 
not  allowed  when  you  use  a  label  to  reference  a  statement.  For  example: 

200  GOTO  Ye8_routlne 

You  can  reference  a  label  almost  anywhere  you  can  reference  a  line 
number.  However,  there  are  the  following  exceptions: 

•  You  cannot  compare  a  label  with  the  value  returned  by  the  ERL 
function. 

•  You  cannot  reference  a  label  in  an  IF  . . .  THEN  .  . .  ELSE  statement 
without  using  the  keyword  GOTO  or  GO  TO.  You  can  use  the 
implied  GOTO  form  only  to  reference  a  line  number.  In  the  following 
example,  the  GOTO  keyword  is  not  required  in  statement  100  because 
the  reference  is  to  a  line  number.  Because  statement  200  references 
labels,  the  GOTO  keyword  is  required. 

Example 

100  IF  AX  •  BX 
THEN  1000 
ELSE  1050 

200  IF  A$  •  "YES* 

THEN  GOTO  Yes 
ELSE  GOTO  No 


1.1.3  Statements 

A  BASIC-PLUS-2  statement  consists  of  a  statement  keyword  and  optional 

operators  and  operands.  For  example,  both  of  these  statements  are  valid: 

400  LET  AX  -  634X  +  (SUMX  -  DIFX) 

PRINT  AX 

BASIC-PLUS-2  statements  are  either  executable  or  nonexecutable: 

•  Executable  statements  perform  operations  (for  example,  PRINT, 
GOTO,  and  READ). 

•  Nonexecutable  statements  describe  the  characteristics  and  arrangement 
of  data,  specify  usage  information,  and  serve  as  comments  in  the 
source  program  (for  example,  DATA,  DECLARE,  and  REM). 
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BASIC-PLUS-2  can  accept  and  process  one  statement  on  a  line  of  text, 
several  statements  on  a  line  of  text,  multiple  statements  on  multiple  lines 
of  text,  and  single  statements  continued  over  several  lines  of  text.  Each 
line  of  program  text  is  associated  with  the  last  specified  line  number,  and 
each  must  contain  a  keyword. 


1. 1.3.1  Keywords 

Every  BASIC-PLUS-2  statement  except  LET  and  empty  statements  must 
begin  with  a  keyword.  A  keyword  is  a  reserved  element  of  the 
BASIC-PLUS-2  language.  Keywords  are  used  to  do  the  following: 

•  Define  data  and  user  identifiers 

•  Perform  operations 

•  Invoke  built-in  functions 

NOTE 

Keywords  are  reserved  words  and  cannot  be  used  as  user 
identifiers,  such  as  variable  names,  labels,  or  names  for  MAP  or 
COMMON  areas. 

Keywords  cannot  be  used  in  any  context  other  than  as  BASIC-PLUS-2 
keywords.  The  assignment  STRINGS  =  "YES",  for  example,  is  invalid 
because  STRINGS  is  a  reserved  BASIC-PLUS-2  keyword  and  therefore 
cannot  be  used  as  a  variable.  Appendix  A  in  this  manual  contains  a  list  of 
BASIC-PLUS-2  reserved  keywords. 

A  BASIC-PLUS-2  keyword  cannot  have  embedded  spaces  and  cannot  be 
split  across  lines  of  text.  There  must  be  a  space,  tab,  or  special  character 
such  as  a  comma  between  the  keyword  and  any  other  variable  or  operator. 


Some  keywords  use  two  words.  In  this  case,  their  spacing  requirements 
vary,  as  shown  in  Table  1-1. 
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Table  1-1: 

Keyword  Space  Requirements 

Optional 

Space 

Required  Space 

No  Space 

GO  TO 

BY  DESC 

FNEND 

GO  SUB 

BY  REF 

FNEXIT 

ON  ERROR 

BY  VALUE 

FUNCTIONEND 

END  DEF 

FUNCTIONEXIT 

END  FUNCTION 

NOECHO 

END  IF 

SUBEND 

END  SELECT 

END  SUB 

EXIT  DEF 

EXIT  FUNCTION 

EXIT  SUB 

INPUT  LINE 

MAP  DYNAMIC 

MAT  INPUT 

MAT  LINPUT 

MAT  PRINT 

MAT  READ 

1.1. 3.2  Single-Statement  Lines  and  Continued  Statements 

A  single-statement  line  consists  of  one  statement  on  one  numbered  line, 
or  one  statement  continued  over  two  or  more  text  lines.  For  example: 

30  PRINT  B  ♦  C  /  12 

This  single-statement  line  has  a  line  number,  the  keyword  (PRINT),  the 
operators  (♦,  /),  and  the  operands  (B,  C,  12). 

You  can  have  a  single  statement  span  several  text  lines  by  typing  an 
ampersand  (&)  and  the  RETURN  key.  BASIC-PLUS-2  ignores  spaces  or 
tabs  between  the  ampersand  and  the  carriage  return.  For  example: 

100  OPEN  "SAMPLE. DAT"  AS  FILE  2%,  k 
SEQUENTIAL  VARIABLE,  k 
MAP  ABC 
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The  ampersand  continuation  character  may  be  used  but  is  not  required  for 
continued  REM  statements.  The  following  example  is  valid: 

REM  This  is  a  remark 

And  this  is  also  a  remark 

You  can  continue  any  BASIC-PLUS-2  statement,  but  you  cannot  con¬ 
tinue  a  string  literal  or  BASIC-PLUS-2  keyword.  The  following  example 
generates  the  error  message  "Unterminated  string  literal." 

200  PRINT  "IF-THEN-ELSE-  k 
END-IF" 

This  example  is  valid: 

200  PRINT  "IF-THEN-ELSE-";  k 
"END-IF" 

A  more  efficient  way  to  continue  string  literals  is  to  use  the  string  concate¬ 
nation  operator  (  +  ): 

200  PRINT  "IF-THEN-ELSE-"  k 

+  "END-IF" 

BASIC-PLUS-2  concatenates  the  four  string  literals  at  compilation  and 
stores  them  as  one  string.  When  the  PRINT  statement  executes, 
BASIC-PLUS-2  displays  the  one  concatenated  string  literal  rather  than 
four  separate  string  literals,  thereby  causing  your  program  to  execute  faster 
and  more  efficiently. 

Continued  statements  do  not  have  line  numbers,  although  the  compiler 
counts  and  numbers  them  as  sublines. 


1.1. 3.3  Multi-Statement  Lines 

Multi-statement  lines  contain  several  statements  on  one  line  of  text, 
multiple  statements  on  separate  lines  of  text,  or  some  combination  thereof. 
All  the  statements  on  a  multi-statement  line  are  associated  with  a  single 
line  number. 

Multiple  statements  on  one  line  of  text  must  be  separated  by  backslashes 
( \ ).  For  example: 

40  PRINT  A  \  PRINT  V  \  PRINT  G 

Because  all  statements  are  on  the  same  program  line,  any  reference  to 
line  number  40  refers  to  all  three  statements  and  execution  begins  with 
the  first  statement  on  the  line.  BASIC-PLUS-2  cannot  execute  the  second 
statement  without  executing  the  first  statement. 
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You  can  also  write  a  multi-statement  program  line  that  associates  all 
statements  with  a  single  line  number  by  placing  each  statement  on  a 
separate  line.  This  format  requires  only  a  space  or  tab  at  the  beginning  of 
each  new  line  of  text.  BASIC-PLUS-2  assumes  that  such  an  unnumbered 
line  of  text  is  either  a  new  statement  or  an  IF  statement  clause. 

In  the  following  example,  each  line  of  text  begins  with  a  BASIC-PLUS-2 
statement  and  each  statement  is  associated  with  line  number  400. 

Example 

400  PRINT  A 
PRINT  B 

PRINT  "FINISHED" 

BASIC-PLUS-2  also  recognizes  IF  .  .  .  THEN  .  .  .  ELSE  constructs  seg¬ 
mented  over  several  lines  of  text  and  associates  the  THEN  and  ELSE 
keywords  with  the  preceding  IF  statement.  For  example: 

Example 

100  REM  Determine  if  the  user's  response 
was  YES  or  NO. 

200  IF  (A$  «  "YES")  OR  (A$  =  "Y") 

THEN  PRINT  "You  typed  YES" 

ELSE  PRINT  "You  typed  NO" 

STOP 
END  IF 

The  BASIC-PLUS-2  compiler  assigns  listing  line  numbers  to  the  statements 
as  they  occur  in  the  program.  Blank  lines  are  numbered. 


Example 

00001  100 
00002 
00003  200 
00004 
00005 
00006 
00007 


REM  Determine  if  the  user's  response 
was  YES  or  NO. 

IF  (A$  -  "YES")  OR  (A$  «  "Y") 

THEN  PRINT  "You  typed  YES" 

ELSE  PRINT  "You  typed  NO" 

STOP 
END  IF 


You  cannot  use  listing  line  numbers  as  targets  of  branch  statements.  The 
target  of  a  branch  statement  such  as  GOTO  must  be  a  line  number  or  a 
label.  See  the  BASIC-PLUS~2  User's  Guide  for  more  information  on  listing 
file  formats. 
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You  can  use  any  BASIC-PLUS-2  statement  in  a  multi-statement  line;  how¬ 
ever,  a  REM  statement  must  be  the  last  statement  on  a  multi-statement 
line  because  the  compiler  ignores  all  text  following  a  REM  keyword  until  it 
reaches  a  new  line  number.  A  DATA  statement  must  be  the  last  statement 
on  a  multi-statement  line  because  the  compiler  treats  all  text  following  a 
DATA  statement  as  data  until  it  reaches  a  new  line. 

Because  a  leading  space  or  tab  not  followed  by  a  line  number  implies 
a  new  statement  in  a  multi-statement  line,  compiler  commands  and 
immediate  mode  statements  cannot  be  preceded  by  a  space  or  tab.  If  you 
enter  a  compiler  command  or  immediate  mode  statement,  you  cannot  add 
more  continuation  lines  to  the  last  program  line;  if  you  attempt  to  do  so, 
BASIC-PLUS-2  signals  an  error. 


1.1.4  Compiler  Directives 

Compiler  directives  are  instructions  for  the  BASIC-PLUS-2  compiler. 

These  instructions  cause  the  BASIC-PLUS-2  compiler  to  perform  certain 

operations  as  it  compiles  the  program. 

By  including  compiler  directives  in  a  program,  you  can: 

•  Place  program  titles  and  subtitles  in  the  header  that  appears  on  each 
page  of  the  listing  file 

•  Place  a  program  version  identification  string  in  both  the  listing  file  and 
object  module 

•  Start  or  stop  the  inclusion  of  listing  information  for  selected  parts  of  a 
program 

•  Start  or  stop  the  inclusion  of  cross  reference  information  for  selected 
parts  of  a  program 

•  Include  BASIC-PLUS-2  code  from  another  source  file 

•  Conditionally  compile  parts  of  a  program 

•  Terminate  compilation 

•  Display  messages  during  the  compilation 
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Follow  these  rules  when  using  compiler  directives: 

•  Compiler  directives  must  begin  with  a  percent  sign. 

•  Compiler  directives  must  be  the  only  text  on  the  line  (except  for 
%IF-%THEN-%ELSE-%END-%IF). 

•  Compiler  directives  cannot  appear  within  a  quoted  string. 

•  Compiler  directives  must  be  preceded  by  a  space,  tab,  or  line  number. 

See  the  BASIC-PLUS-l  User's  Guide  and  Chapter  3  in  this  manual  for  more 
information  on  compiler  directives. 


1.1.5  Comments 

Documentation  within  a  program  clarifies  and  explains  source  program 
structure.  These  explanations,  or  comments,  can  be  combined  with  code 
to  create  a  more  readable  program  without  affecting  program  execution. 
Comments  can  appear  in  two  forms: 

•  Comment  fields  (including  empty  statements) 

•  REM  statements 


1 . 1 .5. 1  Comment  field 

A  comment  field  begins  with  an  exclamation  point  ( ! )  and  ends  with  a 
carriage  return.  You  supply  text  after  the  exclamation  point  to  document 
your  program.  BASIC-PLUS-2  does  not  execute  text  in  a  comment  field. 
For  example: 

Example 

100  !  FOR  loop  to  initialize  list  Q 

FOR  I  =  1  TO  10 

Q(I)  *  0  !  This  is  a  comment 
NEXT  I 

!  List  now  initialized 

Here,  BASIC-PLUS-2  executes  only  the  FOR  .  .  .  NEXT  loop.  The  com¬ 
ment  fields,  preceded  by  exclamation  points,  are  not  executed. 
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Comment  fields  help  make  your  program  more  readable  and  allow  you 
to  format  your  program  into  readily  visible  logical  blocks.  They  can  also 
serve  as  target  lines  for  GOTO  and  GOSUB  statements: 

Example 


10 


!  Square  root  program 

j 

INPUT  'Enter  a  number' :A 
PRINT  'SQR  ol  ';A;'i8  ';SQR(A) 

j 

!  More  square  roots? 

! 

INPUT  'Type  "Y"  to  continue,  press  RETURN  to  quit'; ANSI 
GOTO  10  IF  ANSI  *  "Y" 


99  END 

You  can  also  use  an  exclamation  point  to  terminate  a  comment  field,  but 
this  practice  is  not  recommended.  You  should  make  sure  that  there  are  no 
exclamation  points  in  the  comment  field  itself;  otherwise,  BASIC-PLUS-2 
treats  the  text  remaining  on  the  line  as  source  code. 

NOTE 

Comment  fields  in  DATA  statements  are  invalid;  the  BASIC- 
PLUS-2  compiler  treats  the  comments  as  additional  data. 

Empty  statements  consist  of  a  line  number  and  an  exclamation  point. 
Empty  statements  can  make  your  program  more  legible  by  increasing  the 
amount  of  "white  space'  and  visually  separating  logical  program  segments. 
Note  that  you  can  also  include  blank  lines  without  an  exclamation  point 
to  make  your  program  more  legible. 

In  the  following  example,  lines  100  and  300  are  empty  statements. 

Example 

100  I 

!  FOR  loop  to  Initialize  list  Q 
! 

200  FOR  I  •  1  TO  10 

Q(I)  »  0  !  This  Is  a  comment 
NEXT  I 
300  ! 

!  List  is  now  initialized 

In  general,  empty  statements  make  a  program  more  readable. 
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1.1. 5.2  REM  Statements 

A  REM  statement  begins  with  the  REM  keyword  and  ends  when 
BASIC-PLUS-2  encounters  a  new  line  number.  The  text  you  supply 
between  the  REM  keyword  and  the  next  line  number  documents  your 
program.  Like  comment  fields,  REM  statements  do  not  affect  program 
execution.  BASIC-PLUS-2  ignores  all  characters  between  the  keyword 
REM  and  the  next  line  number.  Therefore,  the  REM  statement  can  be 
continued  without  the  ampersand  ( & )  continuation  character  and  should 
be  the  only  statement  on  the  line  or  the  last  of  several  statements  in  a 
multi-statement  line: 

Example 

10  REM  This  Is  an  example 
20  A>5 

B»10 

REM  A  equals  5 
B  equals  10 
30  PRINT  A,  B 

The  REM  statement  is  nonexecutable.  When  you  transfer  control  to  a 
REM  statement,  BASlC-PLUS-2  executes  the  next  executable  statement 
that  lexically  follows  the  referenced  statement. 

NOTE 

Because  BASIC-PLUS-2  treats  all  text  between  the  REM  state¬ 
ment  and  the  next  line  number  as  commentary,  REM  should 
be  used  very  carefully  in  programs  that  follow  the  implied 
continuation  rules.  It  is  recommended  that  you  use  comment 
helds  instead. 

In  the  following  example,  the  conditional  GOTO  statement  in  line  20 
transfers  program  control  to  line  10.  BASIC-PLUS-2  ignores  the  REM 
comment  on  line  10  and  continues  program  execution  at  line  20. 

Example 

10  REM  **  Square  root  program 
20  INPUT  'Enter  a  number' ;A 

PRINT  'SQR  of  ';A;'i8  ':SQR(A) 

INPUT  'Type  "Y"  to  continue,  press  RETURN  to  quit'; ANSI 
GOTO  10  IF  ANSI  =*  "Y" 

40  END 
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1.1.6  Line  Terminators 

In  the  BASIC  environment,  a  program  line  ends  with  a  carriage  retum/Iine 
feed  combination  (the  RETURN  key)  followed  by  an  optional  space  or  tab 
and  a  new  line  number.  An  ampersand  ( & )  followed  by  a  carriage  return 
ends  a  line  of  text,  but  not  the  program  line.  All  statements  between  the 
first  line  number  and  the  next  line  number  are  associated  with  the  first 
line  number. 


1.1.7  Lexical  Order 

Lexical  order  refers  to  the  order  in  which  the  statements  in  a  program  are 
compiled.  In  general  terms,  BASIC-PLUS-2  compiles  program  lines  in 
sequential  order:  multiple  statements  on  a  line  of  text  are  processed  from 
left  to  right,  and  lines  of  text  are  processed  from  top  to  bottom. 

Some  BASIC -PLUS-2  statements,  such  as  comments  and  MAP  declara¬ 
tions,  are  nonexecutable.  If  program  control  passes  to  a  nonexecutable 
statement,  the  BASIC-PLUS-2  compiler  executes  the  first  statement  that 
lexically  follows  the  nonexecutable  statement. 


1.2  BASIC-PLUS-2  Character  Set 

BASIC-PLUS-2  uses  the  full  ASCII  character  set  to  define  alphanumeric 
and  special  characters  that  are  used  in  string  variables.  This  includes  the 
following: 

•  The  letters  A  through  Z,  both  upper-  and  lowercase 

•  The  digits  0  through  9 

•  Special  characters 

See  the  BASIC-PLUS-2  User's  Guide  for  the  full  ASCII  character  set  and 
character  values. 

The  BASIC-PLUS-2  compiler  does  not  distinguish  between  upper-  and 
lowercase  letters  except  in  string  literals  or  within  a  DATA  statement.  The 
BASIC-PLUS-2  compiler  does  not  process  characters  in  REM  statements  or 
comment  fields,  nor  does  it  process  nonprinting  characters  unless  they  are 
part  of  a  string  literal. 
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In  string  literals,  BASIC-PLUS-2  processes  the  following: 

•  Lowercase  letters  as  lowercase 

•  Nonprinting  characters 

The  ASCII  character  NUL  (ASCII  code  0)  and  line  terminators  cannot 
appear  in  a  string  literal.  Use  the  CHR$  function  or  explicit  literal  notation 
to  use  these  characters  and  terminators. 

You  can  use  nonprinting  characters  in  your  program,  for  example,  in  string 
constants,  but  to  do  so  you  must  use  one  of  the  following: 

•  A  predefined  constant  such  as  ESC  or  DEL 

•  The  CHR$  function  to  specify  an  ASCII  value 

•  Explicit  literal  notation 

See  Section  1.5.4  for  more  information  on  explicit  literal  notation. 


1.3  BASIC-PLUS-2  Data  Types 


Each  unit  of  data  in  a  BASIC-PLUS-2  program  has  a  specific  data  type  that 
determines  how  that  unit  of  data  is  to  be  interpreted  and  manipulated  by 
the  BASIC-PLUS-2  compiler.  This  data  type  also  determines  how  many 
storage  bits  make  up  the  unit  of  data. 

BASIC-PLUS-2  recognizes  four  primary  data  types: 

•  Integer 

•  Floating-point 

•  Character  string 

•  Record  File  Address  (RFA) 

Integer  data  is  stored  as  binary  values  in  a  byte,  word,  or  longword. 

These  values  correspond  to  the  BASIC-PLUS-2  data  type  keywords  BYTE, 
WORD,  and  LONG;  these  are  all  subtypes  of  the  type  INTEGER. 

Floating-point  values  are  stored  using  a  signed  exponent  and  a  binary 
fraction.  BASIC-PLUS-2  allows  only  single  and  double  floating-point 
formats.  These  formats  correspond  to  the  BASIC-PLUS-2  data-type 
keywords  SINGLE  and  DOUBLE;  these  are  both  subtypes  of  the  type 
REAL. 
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Character  data  consists  of  strings  of  bytes  containing  ASCII  code  as  binary 
data.  The  first  character  in  the  string  is  stored  in  the  first  byte,  the  second 
character  is  stored  in  the  second  byte,  and  so  on.  BASIC-PLUS-2  allows 
up  to  32767  characters  for  a  STRING  data  element. 


In  addition  to  this  data  type,  BASIC-PLUS-2  also  recognizes  a  special 
RFA  data  type  to  provide  information  about  a  record's  file  address.  An 
RFA  uniquely  specifies  a  record  in  a  file:  you  can  access  RMS  files  of  any 
organization  by  the  record's  file  address.  By  specifying  the  disk  address  of 
a  record,  RMS  retrieves  the  record  at  that  address.  Accessing  records  by 
RFA  is  more  efficient  and  faster  than  other  forms  of  random  record  access. 
The  RFA  data  type  can  only  be  used  for  the  following: 

•  RFA  operations  (the  GETRFA  function  and  the  GET  and  FIND 
statements) 

•  Assignments  to  other  variables  of  the  RFA  data  type 

•  Comparisons  with  other  variables  of  the  RFA  data  type  with  the  equal 
to  (=)  and  not  equal  to  (  <>  )  relational  operators 

•  Formal  and  actual  parameters 

•  DEF  and  function  results 


You  cannot  declare  a  constant  of  the  RFA  data  type,  nor  can  you  use 
variables  for  any  arithmetic  operations. 


RFA 


The  RFA  data  type  requires  six  bytes  of  information.  See  the 
BASIC-PLUS-2  User's  Guide  for  more  information  on  Record  File  Addresses 
and  the  RFA  data  type. 


Table  1-2  lists  BASIC-PLUS-2  data  type  keywords  and  summarizes 
BASIC-PLUS-2  data  types. 


Table  1-2: 

BASIC-PLUS-2  Data  Types 

Data  Type 

Precision 

Keyword 

Size 

Range 

(Decimal  Digits) 

Integer 

BYTE 

8  bits 

-128  to  +127 

NA 

WORD 

16  bits 

-32768  to  +32767 

NA 

LONG 

32  bits 

-2147483648  to 

NA 

+2147483647 
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Table  1-2  (Cont,):  BASIC-PLUS-2  Data  Types 


Data  Type 
Keyword 

Size 

Range 

Precision 
(Decimal  Digits) 

Real 

SINGLE 

32  bits 

.29  •  10"^“  to 

1.7  ♦  10^® 

6 

DOUBLE 

64  bits 

.29  •  10"®®  to 

1.7  •  10®® 

16 

String 


STRING 

One 

character 
per  byte 

Max  =  32767 

NA 

RFA 

RFA 

6  bytes 

NA 

NA 

In  Table  1-2,  REAL  and  INTEGER  are  generic  data  type  keywords  that 
specify  floating-point  and  integer  storage,  respectively.  If  you  use  the 
REAL  or  INTEGER  keywords  to  type  data,  the  actual  data  type  (SINGLE, 
DOUBLE,  BYTE,  WORD,  or  LONG)  depends  on  the  current  default.  If 
you  do  not  explicitly  type  one  of  the  appropriate  subtypes,  BASIC-PLUS-2 
uses  the  current  subtype  defaults  for  REAL  and  INTEGER. 

You  can  specify  data  type  defaults  in  the  BASIC  environment  with  the 
SET  and  COMPILE  commands,  or  in  a  program  module  with  the  OPTION 
statement.  You  can  also  specify  whether  program  values  are  to  be  typed 
implicitly  or  explicitly.  The  following  sections  discuss  data  type  defaults 
and  implicit  and  explicit  data  typing. 
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1.3.1  Implicit  Data  Typing 

You  can  implicitly  assign  a  data  type  to  program  values  by  adding  a  suffix 
to  the  variable  name  or  integer  constant.  If  you  do  not  specify  any  suffix, 
the  variable  or  integer  constant  is  assigned  the  current  default  data  type. 

The  following  rules  apply  for  implicit  data  typing; 

•  A  dollar  sign  suffix  ( $ )  specifies  STRING  storage. 

•  A  percent  sign  suffix  ( % )  specifies  INTEGER  storage. 

•  No  special  suffix  character  specifies  storage  of  the  default  type,  which 
can  be  INTEGER  or  REAL. 

With  implicit  data  typing,  the  range  and  precision  for  program  values  are 
determined  by  the  corresponding  default  data  sizes  or  subtypes: 

•  BYTE,  WORD,  or  LONG  for  INTEGER  values 

•  SINGLE,  or  DOUBLE  for  REAL  values 

The  default  data  type  is  determined  by  one  of  the  following: 

•  The  system  default  (REAL) 

•  The  data  type  set  for  the  BASIC  environment  with  the  SET  or 
COMPILE  compiler  command 

•  The  data  type  set  for  the  BASIC  environment  with  the  BASIC  state¬ 
ment  OPTION 

The  BASIC -PLUS-2  qualifiers  for  the  SET  and  COMPILE  commands  are 
described  in  Chapter  2  of  this  manual. 

Note  that  if  you  compile  your  program  with  the  /TYPE_DEFAULT=EXPLICIT 
qualifier,  you  can  still  add  the  appropriate  suffixes  to  your  variable  names 
or  constant  values.  The  suffixes  are  useful  because  they  identify  the  data 
type  of  the  variable  or  constant  immediately;  the  reader  does  not  have 
to  refer  to  the  declarations  at  the  top  of  the  program  to  see  which  data 
type  applies  to  a  particular  program  value.  However,  with  the  /TYPE— 
DEFAULT=EXPLICIT  qualifier  you  must  still  explicitly  assign  data  types  to 
all  program  values,  or  BASIC-PLUS-2  signals  an  error. 

It  is  considered  good  programming  practice  to  use  explicit  data  typing 
because  implicit  data  typing  is  dependent  on  compilation  defaults.  These 
defaults  may  change,  thereby  affecting  the  precision  of  the  program 
values. 


1-16  Program  Elements  and  Structure 


1.3.2  Explicit  Data  Typing 


Explicit  data  typing  means  that  you  use  a  declarative  statement  to  spec¬ 
ify  the  type,  range,  and  precision  of  your  program  values.  Declarative 
statements  associate  attributes  such  as  data  type  and  value  with  user 
identifiers. 

In  the  following  example,  the  first  DECLARE  statement  associates  the 
constant  value  03060  and  the  STRING  data  type  with  a  constant  named 
zip^code.  The  second  DECLARE  statement  associates  the  STRING  data 
type  with  emp-Jiame,  the  DOUBLE  data  type  with  with-Jax,  and  the 
SINGLE  data  type  with  int—rate.  No  constant  values  are  associated  with 
identifiers  in  the  second  DECLARE  statement  because  they  are  variable 
names. 

Example 

100  DECLARE  STRING  CONSTANT  zip.code  =  "03060" 

DECLARE  STRING  emp.name.  DOUBLE  with.tax,  SINGLE  Int.rate 

With  explicit  data  typing,  each  program  variable  within  a  program  can 
have  a  different  range  and  precision.  You  can  explicitly  assign  data 
types  to  variables,  constants,  arrays,  parameters,  and  functions;  therefore, 
integer  data  does  not  have  to  take  the  compilation  default  types.  Explicit 
data  typing  gives  you  more  control  over  your  program. 

Using  the  REAL  and  INTEGER  keywords  to  explicitly  type  program 
values  allows  you  to  write  programs  that  are  transportable  across  systems, 
because  these  data  type  keywords  specify  that  all  floating-point  and 
integer  data  take  the  current  defaults  for  REAL  and  INTEGER.  The  data 
type  INTEGER,  for  example,  specifies  only  that  the  constant  or  variable 
is  an  integer.  The  actual  subtype  (BYTE,  WORD,  or  LONG)  depends  on 
the  default  set  with  the  COMPILE  or  SET  command  or  with  the  OPTION 
statement. 

You  can  also  specify  a  particular  data  type  size  for  values  declared 
INTEGER  or  REAL  with  compilation  qualifiers.  The  /DOUBLE  quali¬ 
fier,  for  instance,  specifies  that  all  data  typed  REAL  are  to  be  treated  as 
double-precision  data. 

The  /TYPE_DEFAULT=EXPLIC1T  qualifier  or  OPTION  TYPE=EXPLICIT 
statement  allows  you  to  specify  that  all  program  data  must  be  explicitly 
typed.  Compiling  a  program  with  /TYPE_DEFAULT=  EXPLICIT  or 
specifying  OPTION  TYPE=EXPLICIT  means  that  any  program  value  not 
explicitly  declared  causes  BASIC-PLUS-2  to  signal  an  error. 
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It  is  recommended  that  you  use  the  explicit  data  typing  features  of  BASIC- 
PLUS-2  for  new  applications.  See  the  BASIC-PLUS-2  User's  Guide  for  more 
information. 


1.4  Variables 

A  variable  is  a  named  quantity  whose  value  can  change  during  program 
execution.  Each  variable  name  refers  to  a  location  in  the  program's  storage 
area.  Each  location  can  hold  only  one  value  at  a  time.  Variables  of  all 
data  types  can  have  subscripts  that  indicate  their  position  in  an  array.  You 
can  declare  variables  implicitly  or  explicitly. 

Depending  on  the  program  operations  specified,  the  value  of  a  variable 
can  change  from  statement  to  statement.  BASIC-PLUS-2  uses  the  most 
recently  assigned  value  when  performing  calculations.  This  value  remains 
in  effect  until  a  new  value  is  assigned  to  the  variable. 

BASIC-PLUS-2  accepts  these  general  types  of  variables: 

•  Floating-point 

•  Integer 

•  String 

•  RFA 

See  the  BASIC-PLUS-2  User's  Guide  for  more  information  on  RFA 
variables. 


1.4.1  Variable  Names 

The  name  given  to  a  variable  depends  on  whether  the  variable  is  internal 
or  external  to  the  program  and  whether  the  variable  is  implicitly  or 
explicitly  declared. 

Variable  names  must  conform  to  the  following  rules: 

•  All  variable  names  except  external  variable  names  can  have  from  1 
through  31  characters.  External  variable  names  must  be  explicitly 
declared  and  can  have  from  1  through  6  RAD-50  characters. 

•  The  first  character  of  all  variable  names  must  be  an  upper-  or  lower¬ 
case  alphabetic  character  (A  through  Z). 
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•  The  last  character  of  a  variable  name  can  be  a  dollar  sign  ( $ )  to 
indicate  a  string  variable  or  a  percent  sign  ( % )  to  indicate  an  integer 
variable. 

•  The  remaining  characters,  if  present,  can  be  any  combination  of  upper- 
or  lowercase  letters  (A  through  Z),  numbers  (0  through  9),  dollar  signs 
($),  underscores  (— ),  or  periods  (.).  The  use  of  underscores  in 
variable  names  helps  improve  readability  and  is  preferred  to  the  use 
of  periods. 

•  Variable  names  cannot  contain  embedded  spaces. 

Note  that  a  program  cannot  have  external,  implicitly  declared  variable 
names  since  all  implicitly  declared  names  except  SUB  subprogram  names 
are  internal  to  the  program. 


1.4.2  Implicitly  Declared  Variables 

BASIC-PLUS-2  accepts  three  types  of  implicitly  declared  variables: 

•  Integer 

•  String 

•  Floating-point  (or  the  default  data  type) 

The  name  of  an  implicitly  declared  variable  defines  its  data  type.  Integer 
variables  end  with  a  percent  sign  ( % ),  string  variables  end  with  a  dollar 
sign  ( $ ),  and  variables  of  the  default  type  (usually  floating-point)  end 
with  any  allowable  character  except  a  percent  sign  or  dollar  sign.  All 
three  types  of  variables  must  conform  to  the  rules  listed  in  Section  1.4.1 
for  naming  variables.  The  current  data  type  default  (INTEGER,  or  REAL) 
determines  the  data  t3rpe  of  implicitly  declared  variables  that  do  not  end 
in  a  percent  sign  or  dollar  sign. 

A  floating-point  variable  is  a  named  location  that  stores  a  single-precision 
floating-point  value.  The  current  default  size  for  floating-point  numbers 
(SINGLE  or  DOUBLE)  determines  the  data  type  of  the  floating-point 
variable.  The  following  are  valid  floating-point  variable  names: 

C  L  .  .  .  5  ID-NUMBER 

Ml  BIG47  STORAGE_LOCATION_FOR_XX 

F67T_J  Z2.  STRESS-VALUE 

If  a  numeric  value  of  a  different  data  type  is  assigned  to  a  floating-point 
variable,  BASIC-PLUS-2  converts  the  value  to  a  floating-point  number. 
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An  integer  variable  is  a  named  location  that  stores  a  single  integer  value. 
The  current  default  size  for  integers  (BYTE,  WORD,  or  LONG)  determines 
the  data  type  of  an  integer  variable.  The  following  are  valid  integer 
variable  names: 

ABCDEFG%  C_8%  RECORD_NUMBER% 

B%  D6E7%  THE_VALUE_I_WANT% 

If  the  default  data  type  is  INTEGER,  the  percent  suffix  ( % )  is  not  neces¬ 
sary. 

If  you  assign  a  floating-point  value  to  an  integer  variable,  BASlC-PLUS-2 
truncates  the  fractional  portion  of  the  value.  It  does  not  round  to  the 
nearest  integer.  For  example: 

100  BX  •  -6.7 

BASIC-PLUS-2  assigns  the  value  -5,  not  -6,  to  the  integer  variable. 

A  string  variable  is  a  named  location  that  stores  strings.  The  following  are 
valid  string  variable  names: 

Cl$  M$  EMPLOYEE_NAME$ 

L_6$  F34G$  TARGET_RECORD$ 

ABC1$  T.$  STORAGE_SHELF_IDENTlFIER$ 

Strings  have  both  value  and  length.  BASIC-PLUS-2  sets  all  string  vari¬ 
ables  to  a  default  length  of  zero  before  program  execution  begins,  with 
the  exception  of  those  variables  in  a  COMMON,  MAP,  or  virtual  array. 
See  the  COMMON  statement  and  the  MAP  statement  in  Chapter  4  of 
this  manual  for  information  on  string  length  in  COMMON  and  MAP  ar¬ 
eas.  See  the  BASIC-PLUS-2  User's  Guide  for  information  on  default  string 
length  in  virtual  arrays. 

During  execution,  the  length  of  a  character  string  associated  with  a  string 
variable  can  vary  from  zero  (signifying  a  null  or  empty  string)  to  32767 
characters. 
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1.4.3  Explicitly  Declared  Variables 


BASIC-PLUS-2  lets  you  explicitly  assign  a  data  type  to  a  variable  or  an 
array.  For  example: 

100  DECLARE  DOUBLE  Interest.rate 

Data  type  keywords  are  described  in  Section  1.1. 3.1.  For  more  information 
on  explicit  declaration  of  variables,  see  the  sections  on  the  COMMON, 
DECLARE,  DIMENSION,  DEF,  FUNCTION,  EXTERNAL,  MAP,  and  SUB 
statements  in  Chapter  4  of  this  manual.  See  also  the  BASIC~PLUS~2  User's 
Guide. 


1.4.4  Subscripted  Variables  and  Arrays 

A  subscripted  variable  references  an  element  of  an  array.  Arrays  can  be 
of  any  valid  data  type.  Subscripted  variables  and  arrays  follow  the  same 
naming  conventions  as  unsubscripted  variables.  Subscripts  follow  the 
variable  name  in  parentheses  and  define  the  variable's  position  in  the 
array.  When  you  create  an  array,  you  specify  the  maximum  size  of  the 
array  (the  bounds)  in  parentheses  following  the  array  name. 

In  the  following  example,  the  DECLARE  statement  sets  the  bounds  of  the 
array  emp-^name  to  1000.  Therefore,  the  maximum  value  for  an  emp—name 
subscript  is  1000.  The  bounds  of  the  array  define  the  maximum  value  for 
a  subscript  of  that  array. 

Example 

100  DECLARE  STRING  emp_name(1000) 

200  FOR  ly.  »  oy  to  loooy, 

INPUT  "Employee  name";emp_neune(lX) 

NEXT  IX 

Subscripts  can  be  any  positive  WORD  integer  value  from  0  through  32767. 

NOTE 

By  default,  BASIC-PLUS-2  signals  an  error  if  a  subscript  is 
larger  than  the  allowable  range.  Note,  however,  that  the 
amount  of  storage  the  system  can  allocate  depends  on  available 
memory.  Therefore,  very  large  arrays  may  cause  an  internal 
allocation  error  even  though  the  subscript  is  still  within  the 
specified  range. 
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An  array  is  a  set  of  data  ordered  in  any  number  of  dimensions.  A  one¬ 
dimensional  array,  like  emp—name{l000),  is  called  a  list  or  vector.  A 
two-dimensional  array,  like  payroll ^data{5, 5),  is  called  a  matrix.  An  array 
of  more  than  two  dimensions,  like  big— array {15, 9, 2),  is  called  a  tensor. 

BASIC-PLUS-2  arrays  are  always  zero  based.  The  number  of  elements  in 
any  dimension  always  includes  element  number  zero.  For  example,  the 
array  emp—name  contains  1001  elements,  since  BASIC-PLUS-2  allocates 
element  zero.  Payroll— data{5, 5)  contains  36  elements  because 
BASIC-PLUS-2  allocates  row  and  column  zero.  For  all  arrays  except 
virtual  arrays,  the  total  number  of  array  elements  cannot  exceed  32767. 

BASIC-PLUS-2  arrays  can  have  up  to  eight  dimensions.  You  can  specify 
the  type  of  data  the  array  contains  with  data  type  keywords.  Table  1-2 
lists  BASIC-PLUS-2  data  types. 

An  element  in  a  one-dimensional  array  has  a  variable  name  followed  by 
one  subscript  in  parentheses.  There  can  be  a  space  between  the  array 
name  and  the  subscript.  For  example: 

A(6%) 

B  (6X) 

C$  (6%) 

A(6%)  refers  to  the  seventh  item  in  this  list: 

A(0%)  A(l%)  k{2%)  A(3%)  A(4%)  A(5X)  A(6%) 

An  element  in  a  two-dimensional  array  has  two  subscripts,  in  parentheses, 
following  the  variable  name.  The  first  subscript  specifies  the  row  number 
and  the  second  subscript  specifies  the  column  number.  Use  a  comma  to 
separate  the  subscripts.  You  can  include  a  space  between  the  array  name 
and  the  subscripts  if  you  like.  For  example: 

A  (7X.2X)  AX(4%.6%)  A$  (10%. 10%) 
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In  the  following  figure,  the  arrow  points  to  the  element  specified  by  the 
subscripted  variable  A%(4%,6%): 


COLUMNS 

0123456 


R  0 
0  1 
W2 
S  3 
4 


0  0  0  0  0 
0  0  0  0  0 
0  0  0  0  0 
0  0  0  0  0 
0  0  0  0  0 


0  0 
0  0 
0  0 
0  0 
0  0 


•  A%(4%,6%) 

ZK-5549-86 


An  element  in  an  array  has  as  many  subscripts  as  there  are  dimensions. 

Although  a  program  can  contain  a  variable  and  an  array  with  the  same 
name,  this  is  poor  programming  practice.  Variable  A  and  the  array 
A(3%,3%)  are  separate  entities  and  are  stored  in  completely  separate 
locations,  so  it  is  a  good  idea  to  give  them  different  names. 

Note  that  a  program  cannot  contain  two  arrays  with  the  same  name  but 
a  different  number  of  subscripts.  For  example,  the  arrays  A(3%)  and 
A(3%,3%)  are  invalid  in  the  same  program. 

BASIC-PLUS-2  arrays  can  be  redimensioned  at  run  time.  See  the 
BASIC-PLUS-2  User’s  Guide  for  more  information  on  arrays. 


1.4.5  Initialization  of  Variables 

BASIC-PLUS-2  sets  variables  to  zero  or  null  values  at  the  start  of  program 
execution.  Variables  initialized  by  BASIC-PLUS-2  include  the  following: 

•  Numeric  variables  and  in-storage  array  elements  (except  those  in  MAP 
or  COMMON  statements). 

•  String  variables  (except  those  in  MAP  or  COMMON  statements). 

•  Variables  in  subprograms.  Subprogram  variables  are  initialized  to  zero 
or  the  null  string  each  time  the  subprogram  is  called. 
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BASIC-PLUS-2  does  not  initialize  the  following: 

•  Virtual  arrays 

•  Variables  in  MAP  and  COMMON  areas 

NOTE 

Variables  in  a  MAP  statement  referenced  in  an  OPEN  statement 
are  initialized  to  zero  or  the  null  string  when  the  file  is  opened. 
You  can  also  use  MACRO- 11  routines  to  initialize  MAP  and 
COMMON  areas.  See  the  BASIC-PLUS-2  User's  Guide  for  more 
information. 


1.5  Constants 

A  constant  is  a  numeric  or  character  literal  that  does  not  change  during 
program  execution.  A  constant  can  also  be  named  and  associated  with  a 
data  type.  BASIC-PLUS-2  allows  the  following  types  of  constants: 

•  Numeric: 

—  Floating-point 
—  Integer 

•  String  (ASCII  characters  enclosed  in  quotation  marks) 

A  constant  of  any  of  these  data  types  can  be  named  with  the  DECLARE 
CONSTANT  statement.  You  can  then  refer  to  the  constant  by  name  in 
your  program.  Refer  to  Section  1.5.3  for  information  on  naming  constants. 

You  can  also  use  a  special  numeric  literal  notation  to  specify  the  value 
and  data  type  of  a  numeric  literal.  Numeric  literal  notation  is  discussed  in 
Section  1.5.4. 

If  you  do  not  specify  a  data  type  for  a  numeric  constant  with  the 
DECLARE  CONSTANT  statement  or  with  numeric  literal  notation,  the 
type  and  size  of  the  constant  is  determined  by  the  default  REAL,  or 
INTEGER  type  set  with  the  SET  or  COMPILE  commands,  or  with  the 
OPTION  statement. 

To  simplify  the  representation  of  certain  ASCII  characters  and  mathemati¬ 
cal  values,  BASIC-PLUS-2  also  supplies  some  predefined  constants. 

The  following  sections  discuss  numeric  and  string  constants,  named 
constants,  numeric  literal  notation,  and  predefined  constants. 
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1.5.1  Numeric  Constants 


A  numeric  constant  is  a  literal  or  named  constant  whose  value  never 
changes.  In  BASIC-PLUS-2,  a  numeric  constant  can  be  either  a  floating¬ 
point  number  or  an  integer.  The  type  and  size  of  a  numeric  constant  is 
determined  by  the  following: 

•  The  system  default  values 

•  The  data  type  qualifiers  specified  with  the  COMPILE  command 

•  The  defaults  set  by  the  SET  command 

•  The  data  type  specified  in  a  DECLARE  CONSTANT  or  OPTION 
statement 

•  Numeric  literal  notation 

If  you  use  a  declarative  statement  to  name  and  declare  the  data  type  of 
a  numeric  constant,  the  constant  is  of  the  type  and  size  specified  in  the 
statement.  For  example: 

30  DECLARE  BYTE  CONSTANT  age  =  12 

This  example  associates  the  numeric  literal  12  and  the  BYTE  data  type 
with  the  identifier  age.  To  specify  a  data  type  for  an  unnamed  numeric 
constant,  you  must  use  the  numeric  literal  notation  format  described  in 
Section  1.5.4. 


1. 5.1.1  Floating-Point  Constants 

A  floating-point  constant  is  a  literal  or  named  constant  with  one  or  more 
decimal  digits,  either  positive  or  negative,  with  an  optional  decimal  point 
and  an  optional  exponent  (E  notation).  If  the  default  data  or  constant  type 
is  INTEGER,  BASIC-PLUS-2  will  treat  the  literal  as  an  INTEGER,  unless  it 
contains  a  decimal  point  or  is  in  E  notation. 

The  following  are  examples  of  floating-point  literals  if  the  default  data 
type  is  REAL: 

-8.738  239.21E-6  .79  299 

The  following  are  examples  of  floating-point  literals  if  the  default  data 
type  is  INTEGER: 

-8.738  239.21E-6  .79  299. 
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Very  large  and  very  small  numbers  can  be  represented  in  E  (exponential) 
notation.  If  a  positive  number  appears  in  E  notation,  it  can  be  preceded 
by  an  optional  plus  sign  (+).  A  negative  number  in  E  notation  must  be 
preceded  by  a  minus  sign  (-).  A  number  can  be  carried  to  a  maximum 
of  6  decimal  places  for  SINGLE  precision,  and  16  decimal  places  for 
DOUBLE  precision. 

To  indicate  E  notation,  a  number  must  be  folloived  by  the  letter  E.  It  also 
must  be  followed  by  an  exponent  sign  and  an  exponent.  The  exponent 
sign  indicates  if  the  exponent  is  either  positive  or  negative  and  is  optional 
only  if  you  are  specifying  a  positive  exponent.  The  exponent  is  an  integer 
constant  (the  power  of  10). 

Table  1-3  compares  numbers  in  standard  and  E  notation. 


Table  1-3:  Numbers  in  E  Notation 


Standard  Notation 

E  Notation 

.0000001 

.lE-06 

1,000,000 

.lE+07 

-10,000,000 

-.lE+08 

100,000,000 

.lE+09 

1,000,000,000,000 

.lE+13 

The  range  and  precision  of  floating-point  constants  are  determined  by  the 
current  default  data  types  or  the  explicit  data  type  used  in  the  DECLARE 
CONSTANT  statement.  However,  there  are  limits  to  the  range  allowed  for 
numeric  data  types.  Table  1-2  lists  BASIC-PLUS-2  data  types  and  ranges. 
BASIC-PLUS-2  signals  the  fatal  error  "Floating  point  error  or  overflow" 
when  your  program  attempts  to  specify  a  constant  value  outside  of  the 
allowable  range  for  a  floating-point  data  type. 
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1 .5. 1 .2  Integer  Constants 

An  integer  constant  is  a  literal  or  named  constant,  either  positive  or 
negative,  with  no  fractional  digits  and  an  optional  trailing  percent  sign 
( % ).  The  percent  sign  is  required  for  integer  literals  and  constants  only  if 
the  default  type  is  not  INTEGER. 

The  following  are  examples  of  integer  constants  if  the  default  data  type  is 
REAL: 

81257%  -3477%  79% 

The  following  are  examples  of  integer  constants  if  the  default  data  type  is 
INTEGER: 

81267  -3477  79 

The  range  of  allowable  values  for  integer  constants  is  determined  by 
either  the  current  default  integer  data  type  or  the  explicit  data  type  used 
in  the  DECLARE  CONSTANT  statement.  Table  1-2  lists  BASIC-PLUS-2 
data  types  and  ranges.  BASIC-PLUS-2  signals  the  error  "Integer  error  or 
overflow"  for  an  integer  constant  outside  the  applicable  range. 

If  you  want  BASIC-PLUS-2  to  treat  numeric  literals  as  integer  numbers, 
you  must  do  one  of  the  following: 

•  Set  the  default  data  type  to  INTEGER 

•  Specify  OPTION  CONSTANT  TYPE  =  INTEGER 

•  Make  sure  the  literal  has  a  percent  sign  suffix 

•  Use  explicit  literal  notation 

The  BASIC-PLUS-2  compiler  must  convert  numeric  literals  when  assigning 
them  to  integer  variables  if  they  have  different  data  types.  This  means 
that  your  program  runs  somewhat  slower  than  it  would  if  integer  values 
were  explicitly  declared.  You  can  prevent  this  conversion  step  if  you  do 
the  following: 

•  Set  the  default  data  type  to  INTEGER 

•  Specify  OPTION  CONSTANT  TYPE  =  INTEGER 

•  Use  percent  signs  for  integer  constants 

•  Use  numeric  literal  notation 

•  Use  named  integer  constants 
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NOTE 


You  cannot  use  percent  signs  in  integer  constants  that  appear  in 
DATA  statements.  An  attempt  to  do  so  causes  BASIC-PLUS-2 
to  signal  the  error  message  "Data  format  error"  (ERR=50). 


1.5.2  String  Constants 

String  constants  are  either  string  literals  or  named  constants.  A  string 
literal  is  a  series  of  characters  enclosed  in  string  delimiters.  Valid  string 
delimiters  are  as  follows: 

•  Double  quotation  marks  ("text") 

•  Single  quotation  marks  ('text') 

You  can  embed  double  quotation  marks  within  single  quotation  marks 
('this  is  a  "text"  string')  and  vice  versa  ("this  is  a  'text'  string").  Note, 
however,  that  BASIC-PLUS-2  does  not  accept  incorrectly  paired  quotation 
marks  and  that  only  the  outer  quotation  marks  must  be  paired.  The 
following  character  strings,  for  example,  are  valid: 

"The  record  number  does  not  exist . " 

"I'm  here ! " 

"The  terminating  'condition'  is  equal  to  A$." 

"REPORT  543" 

The  following  strings  are  not  valid: 

"Quotation  marks  that  do  not  match' 

"No  closing  quotation  mark 

Characters  in  string  constants  can  be  letters,  numbers,  spaces,  tabs,  or  any 
ASCII  character  except  a  line  terminator  or  the  NUL  character  (ASCII  code 
0).  If  you  need  a  string  constant  that  contains  a  NUL,  you  should  use  the 
NUL  predefined  constant,  or  explicit  literal  notation.  See  Section  1.5.4  in 
this  manual  for  information  on  explicit  literal  notation. 

The  BASIC-PLUS-2  compiler  determines  the  value  of  the  string  constant 
by  scanning  all  its  characters.  For  example,  because  of  the  number 
of  spaces  between  the  delimiters  and  the  characters,  these  two  string 
constants  are  not  the  same: 

"  END-OF-FILE  REACHED  " 

"END-OF-FILE  REACHED" 
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BASIC-PLUS-2  stores  every  character  between  delimiters  exactly  as  you 
type  it  into  the  source  program,  including  the  following: 

•  Lowercase  letters  (a  through  z) 

•  Leading,  trailing,  and  embedded  spaces 

•  Tabs 

•  Special  characters 

The  delimiting  quotation  marks  are  not  printed  when  the  program  is 
executing.  The  value  of  the  string  constant  does  not  include  the  delimiting 
quotation  marks. 

Example 

300  PRINT  "END-OF-FILE  REACHED" 

END 

Output 

END-OF-FILE  REACHED 

Note,  however,  that  BASIC-PLUS-2  prints  double  or  single  quotation 
marks  when  they  are  enclosed  in  a  second  paired  set: 

Example 

20  PRINT  'FAILURE  CONDITION:  "RECORD  LENGTH"' 

END 

Output 

FAILURE  CONDITION:  "RECORD  LENGTH" 
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1.5.3  Named  Constants 


BASIC-PLUS-2  allows  you  to  name  constants.  You  can  assign  a  name  to  a 
constant  that  is  either  internal  or  external  to  your  pro^am  and  refer  to  the 
constant  by  name  throughout  the  program.  This  naming  feature  is  useful 
for  the  following  reasons: 

•  If  a  commonly  used  constant  must  be  changed,  you  need  to  make  only 
one  change  in  your  program. 

•  A  logically  named  constant  makes  your  program  easier  to  understand. 

You  can  use  named  constants  anywhere  you  can  use  a  constant,  for 
example,  to  specify  the  number  of  elements  in  an  array. 

You  cannot  change  the  value  of  an  explicitly  named  constant  during 
program  execution.  To  change  the  value  of  a  constant,  you  must  change 
the  program  statement  that  names  the  constant  and  declares  its  value,  and 
then  recompile  the  program. 


1. 5.3.1  Naming  Constants  Within  a  Program  Unit 

You  name  constants  within  a  program  unit  with  the  DECLARE  statement. 

Example 

20  DECLARE  DOUBLE  CONSTANT  prelerred.rate  «  .147 
DECLARE  SINGLE  CONSTANT  normai.rate  *  .162 
DECLARE  DOUBLE  CONSTANT  risky.rate  «  .175 

new.bal  *  old_bal  ♦  (1  ♦  prelerred_rate)"year8_payment 

When  interest  rates  change,  only  three  lines  have  to  be  changed  rather 
than  every  line  that  contains  an  interest  rate  constant. 

Constant  names  must  conform  to  the  rules  for  naming  internal,  explicitly 
declared  variables  listed  in  Section  1.4.1.  Note  that  constant  names  cannot 
have  embedded  spaces. 
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The  value  associated  with  a  named  constant  can  be  a  compile-time 
expression  as  well  as  a  literal  value,  as  shown  in  the  following  example: 

Example 

20  DECLARE  STRING  CONSTANT  Congrats  «  k 

"+ . +"  +  LF  +  CR  +  k 

”1  Congratulations!  i ”  CR  CR  k 

H  + - +  H 


80  PRINT  Congrats 


100  PRINT  Congrats 

Named  constants  can  save  you  programming  time  because  you  do  not 
have  to  retype  the  value  every  time  you  want  to  display  it.  Named 
constants  can  save  you  execution  time  because  the  named  constant  is 
known  at  compilation  time. 

Valid  operators  in  DECLARE  CONSTANT  expressions  include  all  valid 
arithmetic,  relational,  and  logical  operators  except  exponentiation.  You 
cannot  use  built-in  functions  in  DECLARE  CONSTANT  expressions. 

You  can  specify  the  value  of  a  constant  with  an  expression  for  STRING 
and  INTEGER  data  types,  but  not  for  floating-point  constants.  Only 
STRING  and  INTEGER  constants  can  be  named  as  expressions  in 
DECLARE  CONSTANT  statements.  The  following  example  illustrates 
the  concept  of  naming  constants  as  expressions: 

50  DECLARE  DOUBLE  CONSTANT  k 
mln.value  *  0 
max.value  «  PI 

You  can  specify  only  one  data  type  in  a  DECLARE  CONSTANT  statement. 
To  declare  a  constant  of  a  different  data  type,  you  must  use  a  second 
DECLARE  CONSTANT  statement. 
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1 .5.3.2  Naming  Constants  External  to  a  Program  Unit 

To  declare  constants  outside  the  program  unit,  use  the  EXTERNAL  state¬ 
ment. 

Example 

50  EXTERNAL  WORD  CONSTANT  lE.SUC 

This  line  declares  lE.SUC,  a  success  code,  to  be  an  external  WORD 
constant.  BASIC-PLUS-2  allows  only  WORD  constants.  The  task  builder 
supplies  the  values  for  the  constants  specified  in  EXTERNAL  statements. 

External  constant  names  cannot  exceed  six  characters  and  must  conform  to 
the  rules  for  naming  external  variables  listed  in  Section  1.4.1.  No  external 
constant  name  can  have  embedded  spaces.  In  BASIC-PLUS-2,  the  named 
constant  might  be  a  a  global  constant  declared  in  a  MACRO- 11  program 
or  an  RMS- 11  constant. 


1.5.4  Explicit  Literal  Notation 

You  can  specify  the  value  and  data  type  of  numeric  literals  by  using  a 
special  notation  called  explicit  literal  notation.  The  format  of  this  notation 
is  as  follows: 

[radix]  num-str-lit  [data- type] 

Radix  specifies  an  optional  base,  which  can  be  any  of  the  following: 

A  ASCII 

R  RAD-50 

D  Decimal  (base  10) 

B  Binary  (base  2) 

O  Octal  (base  8) 

X  Hexadecimal  (base  16) 

The  BASIC-PLUS-2  default  radix  is  decimal.  Binary,  octal,  and  hexadeci¬ 
mal  notation  allow  you  to  set  or  clear  individual  bits  in  the  representation 
of  an  integer.  This  feature  is  useful  in  forming  conditional  expressions 
and  in  using  logical  operations.  The  ASCII  radix  causes  BASIC-PLUS-2 
to  translate  a  single  ASCII  character  to  its  decimal  equivalent.  This  deci¬ 
mal  equivalent  is  an  INTEGER  value;  you  specify  whether  the  INTEGER 
subtype  should  be  BYTE,  WORD,  or  LONG. 
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Num-strAit  is  a  numeric  string  literal.  It  can  be  the  digits  0  and  1  when 
the  radix  is  binary,  the  digits  0  through  7  when  the  radix  is  octal,  the 
digits  0  through  F  when  the  radix  is  hexadecimal,  and  the  digits  0  through 
9  when  the  radix  is  decimal.  When  the  radix  is  ASCII,  num-strAit  can  be 
any  valid  ASCII  character.  When  the  radix  is  RAD-50,  num-strAit  must 
be  exactly  three  valid  RAD-50  characters;  if  less  than  three  characters  are 
required,  pad  with  spaces  on  the  left  or  right. 

DataAype  is  an  optional  single  letter  that  corresponds  to  a  data  type 
keyword,  excluding  INTEGER  and  REAL: 

B  BYTE 

W  WORD 

L  LONG 

F  SINGLE 

D  DOUBLE 

C  CHARACTER 


For  example: 

R"'  $"B  Specifies  a  BYTE  decimal  constant  with  a  value  of  27 

R"ABC"W  Specifies  a  WORD  decimal  constant  with  a  value  of  1683 

D"255"L  Specifies  a  LONG  decimal  constant  with  a  value  of  255 

"4000"F  Specifies  a  SINGLE  decimal  constant  with  a  value  of  4000 
-"125"B  Specifies  a  BYTE  decimal  constant  with  a  value  of  -125 

A"M"L  Specifies  a  LONG  integer  constant  with  a  value  of  77 

A"m"B  Specifies  a  BYTE  integer  constant  with  a  value  of  109 


If  you  specify  a  binary,  octal,  or  hexadecimal  radix,  dataAype  must  be  an 
integer.  If  you  do  not  specify  a  data  type,  BASIC-PLUS-2  uses  the  default 
integer  data  type.  For  example: 


B"11111111"B 

B"11111111"W 

B"1111111P' 

B"11111111"F 

X"FF"B 


Specifies  a  BYTE  binary  constant  with  a  value  of  -1  , 
Specifies  a  WORD  binary  constant  with  a  value  of  255 

Specifies  a  binary  constant  of  the  default  data  type  (BYTE, 
WORD,  or  LONG) 

Is  illegal  because  F  is  not  an  integer  data  type 
Specifies  a  BYTE  hexadecimal  constant  with  a  value  of  -1 
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0"377"W 


Specifies  a  WORD  hexadecimal  constant  with  a  value  of  255 
Is  illegal  because  D  is  not  an  integer  data  type 
Specifies  a  BYTE  octal  constant  with  a  value  of  -1 
Specifies  a  WORD  octal  constant  with  a  value  of  255 
Is  illegal  because  G  is  not  an  integer  data  type 


When  you  specify  a  radix  other  than  decimal,  overflow  checking  is  per¬ 
formed  as  if  the  numeric  string  were  an  unsigned  integer.  However, 
when  this  value  is  assigned  to  a  variable  or  used  in  an  expression,  the 
BASIC-PLUS-2  compiler  treats  it  as  a  signed  integer. 

In  the  following  example,  BASIC-PLUS-2  sets  all  eight  bits  in  storage 
location  A.  Because  A  is  a  BYTE  integer,  it  has  only  eight  bits  of  storage. 
Because  the  8-bit  two's  complement  of  1  is  11111111,  its  value  is  -1. 

If  the  data  type  were  W  (WORD),  BASIC-PLUS-2  would  set  the  bits  to 
0000000011111111,  and  its  value  would  be  255. 

Example 

50  DECLARE  BYTE  A 
A  - 

PRINT  A 


Output 


-1 


NOTE 


In  BASIC-PLUS-2,  the  letter  D  can  appear  in  both  the  radix 
position  and  the  data  type  position.  A  letter  D  in  the  radix 
position  specifies  that  the  numeric  string  is  to  be  treated  as  a 
decimal  number  (base  10).  A  letter  D  in  the  data  type  position 
specifies  that  the  value  is  to  be  treated  as  a  double-precision, 
floating-point  constant. 

You  can  use  explicit  literal  notation  to  represent  a  single-character  string 
in  terms  of  its  8-bit  ASCII  value.  For  example: 

[radix]  num-str-lit  C 

The  letter  C  is  an  abbreviation  for  CHARACTER.  The  value  of  the  numeric 
string  must  be  from  0  through  255.  This  feature  lets  you  create  your  own 
compile-time  string  constants  containing  nonprinting  characters. 
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The  following  example  declares  a  string  constant  named  control— g  (ASCII 
decimal  value  7).  When  BASIC-PLUS-2  executes  the  PRINT  statement, 
the  terminal  bell  sounds. 

Example 

30  DECLARE  STRING  CONSTANT  control.g  •  "7"C 
PRINT  coiitrol_g 


1.5.5  Predefined  Constants 


Predefined  constants  are  symbolic  representations  of  either  ASCII  charac¬ 
ters  or  mathematical  values.  They  are  also  called  compile-time  constants 
because  their  value  is  known  at  compilation  rather  than  at  run  time. 

Predefined  constants  help  you  do  the  following: 

•  Format  program  output  to  improve  readability 

•  Make  source  code  easier  to  understand 

Table  1-5  lists  the  predefined  constants  supplied  by  BASIC-PLUS-2,  their 
ASCII  values,  and  their  functions. 

Table  1-5:  Predefined  Constants 


Constant 


Decimal 
ASCII  Value 


Function 


LF  (Line  Feed) 
VT  (Vertical  Tab) 


FF  (Form  Feed) 


BEL  (Bell) 

BS  (Backspace) 


HT  (Horizontal  Tab)  9 


CR  (Carriage  Return)  13 


7 

8 


10 

11 


12 


Sounds  the  terminal  bell 

Moves  the  cursor  one  position  to 
the  left 

Moves  the  cursor  to  the  next 
horizontal  tab  stop 

Moves  the  cursor  to  the  next  line 

Moves  the  cursor  to  the  next 
vertical  tab  stop 

Moves  the  cursor  to  the  start  of 
the  next  page 

Moves  the  cursor  to  the  begin¬ 
ning  of  the  current  line 
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Table  1-5  (Cent.):  Predefined  Constants 


Constant 

Decimal 

ASCII  Value 

Function 

SO  (Shift  Out) 

14 

Shifts  out  for  communications 
networking,  screen  formatting, 
and  alternate  graphics 

SI  (Shift  In) 

15 

Shifts  in  for  communications 
networking,  screen  formatting, 
and  alternate  graphics 

ESC  (Escape) 

27 

Marks  the  beginning  of  an  escape 
sequence 

SP  (Space) 

32 

Inserts  one  blank  space  in 
program  output 

DEL  (Delete) 

127 

Deletes  the  last  character  entered 

PI 

None 

Represents  the  number  PI  with 
the  precision  of  the  default 
floating-point  data  type 

You  can  use  predefined  constants  in  many  ways.  For  instance,  the  fol¬ 
lowing  example  shows  how  to  print  and  underline  a  word  on  a  hardcopy 
terminal. 


Example 

400  PRINT  "NAME:"  +  BS  +  BS  +  BS  ♦  BS  +  BS  +  " _ " 

END 

Output 

NAME: 

The  following  example  shows  how  to  print  and  underline  a  word  on  a 
VTIOO  terminal  screen: 

Example 

400  PRINT  ESC  ♦  "[4mNAME:"  +  ESC  +  " [Om" 

END 

Output 

NAME: 


Note  that  the  m  in  the  above  example  must  be  lowercase. 
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You  can  also  create  your  own  predefined  constants  with  the  DECLARE 
CONSTANT  statement. 

In  the  following  example,  the  first  DECLARE  statement  defines 
underlined— name  as  a  string  constant.  The  second  DECLARE  statement 
defines  D__P/  as  a  DOUBLE  constant  equal  to  the  predefined  constant 
PI.  If  the  default  REAL  data  size  is  SINGLE,  the  program  can  use  both 
single-precision  PI  and  double-precision  D_P/. 

Example 

40  DECLARE  STRING  CONSTANT  imderline(l_n£Lme  *  ESC  +  ”[4inNAME:"  ESC  +  "[Om" 
DECLARE  DOUBLE  CONSTANT  D_PI  *  PI 
PRINT  under lined.name 
PRINT  D_PI. ,PI 


1.6  Expressions 

BASIC-PLUS-2  expressions  consist  of  operands  (numbers,  strings,  con¬ 
stants,  variables,  functions,  and  array  elements)  separated  by  arithmetic, 
string,  relational,  and  logical  operators. 

Almost  all  BASIC-PLUS-2  expressions  yield  numeric  values.  The  only 
exceptions  are  string  concatenation  expressions  and  invocations  of  string¬ 
valued  functions.  By  using  different  combinations  of  numeric  operators 
and  operands,  and  by  using  the  resulting  values,  you  can  produce  the 
following: 

•  Numeric  expressions 

•  String  expressions 

•  Conditional  expressions 

BASIC -PLUS-2  evaluates  expressions  according  to  operator  precedence 
and  uses  the  results  in  program  execution.  Parentheses  can  be  used  to 
group  operands  and  operators,  thus  controlling  the  order  of  evaluation. 

BASIC-PLUS-2  does  not  detect  integer  or  floating-point  overflow  when 
evaluating  expressions.  You  must  make  sure  that  your  calculations  do  not 
overflow;  otherwise,  the  results  will  be  unpredictable. 

The  following  sections  explain  the  types  of  expressions  you  can  create  and 
the  way  BASIC-PLUS-2  evaluates  expressions. 
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1.6.1  Numeric  Expressions 

Numeric  expressions  consist  of  floating-point  or  integer  operands  sep¬ 
arated  by  arithmetic  operators  and  optionally  grouped  by  parentheses. 
Table  1-6  shows  how  numeric  operators  work  in  numeric  expressions. 


Table  1-6:  Arithmetic  Operators 


Operator 

Example 

Use 

+ 

A  +  B 

Add  B  to  A 

- 

A-B 

Subtract  B  from  A 

* 

A  *  B 

Multiply  A  by  B 

/ 

A  /  B 

Divide  A  by  B 

* 

A''B 

Raise  A  to  the  povs^er  B 

A**B 

Raise  A  to  the  power  B 

In  general,  two  arithmetic  operators  cannot  occur  consecutively  in  the 
same  expression.  Exceptions  are  the  unary  plus  and  unary  minus.  The 
following  expressions  are  valid: 

A  «  +  B 
A  »  -  B 
A  »  (-B) 

A  *  +  -  +  -  B 

The  following  expression  is  not  valid: 

A  -  *  B 

An  operation  on  two  numeric  operands  of  the  same  data  type  yields  a 
result  of  that  type.  For  example: 

A%  +  B%  Yields  an  integer  value  of  the  default  type 

G3  *  M5  Yields  a  floating-point  value  if  the  default  type  is  REAL 

It  is  possible  to  assign  a  value  of  one  data  type  to  a  variable  of  a  different 
data  type.  When  this  occurs,  the  data  type  of  the  variable  overrides  the 
data  type  of  the  assigned  value.  The  following  example  assigns  the  value 
32  to  the  integer  variable  A%  even  though  the  floating-point  value  of  the 
expression  is  32.13. 
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200  A%  •  6.1  ♦  6.3 

When  an  expression  contains  operands  with  different  data  types,  the  data 
type  of  the  result  is  determined  by  BASIC-PLUS-2's  data  type  promotion 
rules: 

•  With  one  exception,  BASIC-PLUS-2  promotes  operands  with  different 
data  types  to  the  lowest  common  data  type  that  can  hold  the  largest 
or  most  precise  possible  value  of  either  operand's  data  type. 
BASIC-PLUS-2  then  performs  the  operation  using  that  data  type,  and 
yields  a  result  of  that  data  t)^e. 

•  The  exception  is  that  when  an  operation  involves  SINGLE  and  LONG 
data  types,  BASIC-PLUS-2  promotes  the  LONG  data  type  to  SINGLE 
rather  than  DOUBLE,  performs  the  operation,  and  yields  a  result  of 
the  SINGLE  data  type. 

Note  that  BASIC-PLUS-2  does  sign  extension  when  converting  BYTE 
and  WORD  integers  to  a  higher  INTEGER  data  type  (WORD  or  LONG). 
The  high-order  bit  (the  sign  bit)  determines  how  the  additional  bits  are 
set  when  the  BYTE  or  WORD  is  converted  to  WORD  or  LONG.  If  the 
high-order  bit  is  zero  (positive),  all  higher-order  bits  in  the  converted 
BYTE  or  WORD  are  set  to  zero.  If  the  high-order  bit  is  1  (negative),  all 
higher-order  bits  in  the  converted  BYTE  or  WORD  are  set  to  1. 

Table  1-7  lists  the  data  type  results  possible  in  numeric  expressions  that 
combine  BYTE,  WORD,  LONG,  SINGLE,  and  DOUBLE  data. 


Table  1-7;  Result  Data  Types  in  BASIC-PLUS-2  Expressions 


BYTE 

WORD 

LONG 

SINGLE 

DOUBLE 

BYTE 

BYTE 

WORD 

LONG 

SINGLE 

DOUBLE 

WORD 

WORD 

WORD 

LONG 

SINGLE 

DOUBLE 

LONG 

LONG 

LONG 

LONG 

SINGLE 

DOUBLE 

SINGLE 

SINGLE 

SINGLE 

SINGLE 

SINGLE 

DOUBLE 

DOUBLE 

DOUBLE 

DOUBLE 

DOUBLE 

DOUBLE 

DOUBLE 

For  example,  if  one  operand  is  SINGLE  and  one  operand  is  DOUBLE, 
BASIC-PLUS-2  promotes  the  SINGLE  value  to  DOUBLE,  performs  the 
specified  operation,  and  returns  the  result  as  a  DOUBLE  value.  This 
promotion  is  necessary  because  the  SINGLE  data  type  has  less  precision 
than  the  DOUBLE  value,  whereas  the  DOUBLE  data  type  can  represent  all 
possible  SINGLE  values.  If  BASIC-PLUS-2  did  not  promote  the  SINGLE 
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value  and  the  operation  yielded  a  result  outside  of  the  SINGLE  range,  loss 
of  precision  and  significance  would  occur. 

The  data  types  BYTE,  WORD,  LONG,  SINGLE,  and  DOUBLE  form  a 
simple  hierarchy;  if  all  operands  in  an  expression  are  of  these  data  types, 
the  result  of  the  expression  is  the  highest  data  type  used  in  the  expression. 


1.6.2  String  Expressions 

String  expressions  are  string  entities  separated  by  the  plus  sign  (+).  When 
used  in  a  string  expression,  the  plus  sign  concatenates  strings. 

Example 

80  INPUT  "Type  two  words  to  be  combined” ;A$,  B$ 

C$  =  A$  B$ 

PRINT  C$ 

END 

Output 

Type  two  words  to  be  combined?  rattle 
?  brained 

rattlebrained 

BASIC2 


1.6.3  Conditional  Expressions 

Conditional  expressions  can  be  either  relational  or  logical  expressions. 
Numeric  relational  expressions  compare  numeric  operands  to  determine 
whether  the  expression  is  true  or  false.  String  relational  expressions 
compare  string  operands  to  determine  which  string  expression  occurs  first 
in  the  ASCII  collating  sequence. 

Logical  expressions  contain  integer  operands  and  logical  operators. 
BASIC-PLUS-2  determines  whether  the  specified  logical  expression  is 
true  or  false  by  testing  the  numeric  result  of  the  expression.  Note  that 
in  conditional  expressions,  as  in  any  numeric  expression,  when  BYTE 
and  WORD  operands  are  converted  to  WORD  and  LONG,  the  specified 
operation  is  performed  in  the  higher  data  type,  and  the  result  returned 
is  also  of  the  higher  data  type.  When  one  of  the  operands  is  a  negative 
value,  this  conversion  will  produce  accurate  but  perhaps  confusing  results, 
because  BASIC-PLUS-2  performs  a  sign  extension  when  converting  BYTE 
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and  WORD  integers  to  a  higher  integer  data  type.  See  Section  1.6.1  for 
information  on  integer  conversion  rules. 


1. 6.3.1  Numeric  Relational  Expressions 

Operators  in  numeric  relational  expressions  compare  the  values  of  two 
operands  and  return  either  a  -1  if  the  relation  is  true  or  a  zero  if  the 
relation  is  false.  The  data  type  of  the  result  is  the  default  integer  type. 

Example  1 

10  A  *  10 
B  *  16 

xy.  =  (A  <>  B) 

20  IF  xy,  =  -ly, 

THEN  PRINT  'Relationship  is  true' 

ELSE  PRINT  'Relationship  is  false' 

END  IF 

Output  1 

Relationship  is  true 

Example  2 

10  A  =  10 
B  =  16 
xy.  =  A  =  B 

20  IF  xy,  *  -ly. 

THEN  PRINT  'Relationship  is  true' 

ELSE  PRINT  'Relationship  is  false' 

END  IF 

Output  2 

Relationship  is  false 

Table  1-8  shows  how  numeric  operators  work  in  numeric  relational 
expressions. 


Program  Elements  and  Structure  1-41 


Table  1-8:  Numeric  Relational  Operators 


Operator 

Example 

Meaning 

= 

A  =  B 

A  is  equal  to  B. 

< 

A  <  B 

A  is  less  than  B. 

> 

A  >  B 

A  is  greater  than  B. 

<=  or  =  < 

PQ 

II 

V 

< 

A  is  less  than  or  equal  to  B. 

>  =  or  => 

A  >  =  B 

A  is  greater  than  or  equal  to  B. 

<>  or 
>  < 

A  <>  B 

A  is  not  equal  to  B. 

A  ==  B 

A  and  B  will  print  the  same  because  they  are 
equal  to  six  significant  digits. 

1 .6.3.2  String  Relational  Expressions 

Operators  in  string  relational  expressions  determine  how  BASIC-PLUS-2 
compares  strings.  The  BASIC-PLUS-2  compiler  determines  the  value  of 
each  character  in  the  string  by  converting  it  to  its  ASCII  value.  See  the 
BASIC-PLUS-2  User's  Guide  for  a  list  of  ASCII  values.  BASIC-PLUS-2 
compares  the  strings  character  by  character,  left  to  right,  until  it  finds  a 
difference  in  ASCII  value. 

In  the  following  example,  BASIC-PLUS-2  compares  A$  and  B$  character 
by  character.  The  strings  are  identical  up  to  the  third  character.  Because 
the  ASCII  value  of  Z  (90)  is  greater  than  the  ASCII  value  of  C  (67),  A$  is 
less  than  B$.  BASIC-PLUS-2  evaluates  the  expression  A$  <  B$  as  true 
( -1 )  and  prints  "ABC  comes  before  ABZ." 

Example 

10  At  -  'ABC 
Bt  •  'ABZ* 

20  IF  At  <  Bt 

THEN  PRINT  'ABC  comes  before  ABZ' 

ELSE  IF  At  ««  Bt 

THEN  PRINT  'The  strings  are  identical* 

ELSE  IF  A$  >  B| 

THEN  PRINT  'ABC  comes  alter  ABZ' 

ELSE  PRINT  'Strings  are  equal  but  not  identical' 

END  IF 
END  IF 
END  IF 
END 


1-42  Program  Elements  and  Structure 


If  two  strings  of  differing  lengths  are  identical  up  to  the  last  character 
in  the  shorter  string,  BASIC-PLUS-2  pads  the  shorter  string  with  spaces 
(ASCII  value  32)  to  generate  strings  of  equal  length,  unless  the  operator 
is  the  double  equal  sign  (==).  If  the  operator  is  the  double  equal  sign, 
BASIC-PLUS-2  does  not  pad  the  shorter  string. 

In  the  following  program,  BASIC-PLUS-2  compares  "ABCDE"  to  "ABC  " 
to  determine  which  string  comes  first  in  the  collating  sequence.  "ABC" 
comes  before  "ABCDE"  because  the  ASCII  value  for  space  (32)  is  lower 
than  the  ASCII  value  of  D  (68).  Then  BASIC-PLUS-2  compares  "ABC  " 
with  "ABC"  using  the  double  equal  sign  and  determines  that  the  strings  do 
not  match  exactly  without  padding.  The  third  comparison  uses  the  single 
equal  sign.  BASIC-PLUS-2  pads  "ABC"  with  spaces  and  determines  that 
the  two  strings  match  with  padding. 

Example 

10  A$  -  'ABODE' 

B$  -  'ABC 

PRINT  'B$  comes  before  A$'  IF  B$  <  A$ 

PRINT  'A$  comes  before  B$'  IF  A$  <  B$ 

C$  -  'ABC  ' 

IF  B$  "  Ct 

THEN  PRINT  'B$  exactly  matches  C$' 

ELSE  PRINT  'B$  does  not  exactly  match  C$' 

END  IF 
IF  B$  »  C$ 

THEN  PRINT  'B$  matches  C$  with  padding' 

ELSE  PRINT  'B$  does  not  match  C$' 

END  IF 

Output 

B|  comes  before  A$ 

B$  does  not  exactly  match  C$ 

B$  matches  C$  with  padding 

Table  1-9  shows  how  numeric  operators  work  in  string  relational  expres¬ 
sions.  ^ 
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Table  1-9:  String  Relational  Operators 


Operator 

Example 

Meaning 

■ 

A$  =  B$ 

Strings  A$  and  B$  are  identical  after  the  shorter 

string  has  been  padded  with  spaces  to  equal  the 
length  of  the  longer  string. 

< 

A$  <  B$ 

String  A$  occurs  before  string  B$  in  ASCII 
sequence. 

> 

A$  >  B$ 

String  A$  occurs  after  string  B$  in  ASCII  sequence. 

<=  or  =  < 

A$  <=B$ 

String  A$  is  identical  to  or  precedes  string  B$  in 
ASCII  sequence. 

>  =  or  => 

A$  >  =  B$ 

String  A$  is  identical  to  or  follows  string  B$  in 
ASCII  sequence. 

<>  or 
>  < 

A$  <> 

B$ 

String  A$  is  not  identical  to  string  B$. 

=  = 

A$  ==  B$ 

Strings  A$  and  B$  are  identical  in  composition 
and  length,  without  padding. 

BASIC-PLUS-2  treats  unquoted  strings  typed  in  response  to  the  INPUT 
statement  differently  from  quoted  strings;  it  does  so  by  ignoring  leading 
and  trailing  spaces  and  tabs.  For  example,  it  evaluates  the  quoted  strings 
"ABC"  and  "ABC  "  as  equal  but  not  identical  because  the  ==  operator  does 
not  pad  the  shorter  string  with  spaces.  When  you  input  those  same  strings 
as  unquoted  strings  in  response  to  the  INPUT  prompt,  BASIC-PLUS-2 
evaluates  them  as  equal  and  identical  because  it  ignores  the  trailing 
spaces.  The  LINPUT  statement,  on  the  other  hand,  treats  unquoted 
strings  as  string  literals,  so  the  trailing  spaces  are  part  of  the  string,  and 
BASIC-PLUS-2  evaluates  the  strings  as  equal  but  not  identical. 


1 .6.3.3  Logical  Expressions 

A  logical  expression  can  have  one  of  the  following  formats: 

•  A  unary  logical  operator  and  one  integer  operand 

•  Two  integer  operands  separated  by  a  binary  logical  operator 

•  One  integer  operand 
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Logical  expressions  are  valid  only  when  the  operands  are  integers.  If 
the  expression  contains  two  integer  operands  of  differing  data  types,  the 
resulting  integer  has  the  same  data  type  as  that  of  the  higher  integer 
operand.  For  instance,  the  result  of  an  expression  that  contains  a  BYTE 
integer  and  a  WORD  integer  would  be  a  WORD  integer.  Table  1-7  shows 
how  integer  data  types  interact  with  each  other  in  expressions. 

BASIC-PLUS-2  determines  whether  the  condition  is  true  or  false  by  testing 
the  result  of  the  logical  expression  to  see  whether  any  bits  are  set.  If  no 
bits  are  set,  the  value  of  the  expression  is  zero  and  it  is  evaluated  as 
false;  if  any  bits  are  set,  the  value  of  the  expression  is  nonzero  and  the 
expression  is  evaluated  as  true.  BASIC-PLUS-2  generally  accepts  any 
nonzero  value  in  logical  expressions  as  true.  However,  logical  operators 
can  return  unanticipated  results  unless  -1  is  specified  for  true  values  and 
zero  for  false.  Table  1-10  lists  the  logical  operators. 

NOTE 

It  is  recommended  that  you  use  logical  operators  on  the  results 
of  relational  expressions  to  avoid  obtaining  unanticipated 
results. 


Table  1—10;  Logical  Operators 


Operator 

Example 

Meaning 

NOT 

NOT  A% 

The  bit-by-bit  complement  of  A%.  If  A%  is  true 
(-1),  NOT  A%  is  false  (0). 

AND 

A%  AND  B% 

The  logical  product  of  A%  and  B%.  A%  AND 
B%  is  true  only  if  both  A%  and  B%  are  true. 

OR 

A%  OR  B% 

The  logical  sum  of  A%  and  B%.  A%  OR  B% 
is  false  only  if  both  A%  and  B%  are  false; 
otherwise,  A%  OR  B%  is  true. 

XOR 

A%  XOR  B% 

The  logical  exclusive  OR  of  A%  and  B%.  A% 
XOR  B%  is  true  if  either  A%  or  B%  is  true  but 
not  if  both  are  true. 

EQV 

A%  EQV  B% 

The  logical  equivalence  of  A%  and  B°/o.  A% 
EQV  B%  is  true  if  A%  and  B%  are  both  true  or 
both  false;  otherwise,  the  value  is  false. 

IMP 

A%  IMP  B% 

The  logical  implication  of  A%  and  B%.  A%  IMP 
B%  is  false  only  if  A%  is  true  and  B%  is  false; 
otherwise,  the  value  is  true. 
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The  truth  tables  in  Figure  1-1  summarize  the  results  of  these  logical 
operations.  Zero  is  false;  -1  is  true. 

Figure  1-1:  Truth  Tables 


A% 

NOT  A% 

A% 

B% 

A%  OR  B% 

0 

-1 

0 

0 
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-1 

0 
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-1 

-1 

-1 

-0 

-1 

-1 

-1 

-1 

A% 

B% 

A%  AND  B% 

A% 

B% 

A%  EQV  B% 

0 

0 

0 

0 

0 

-1 

0 

-1 

0 

0 

-1 

0 

-1 

0 

0 

-1 

0 

0 

-1 

-1 

-1 

-1 

-1 

-1 

A% 

B% 

A%  XOR  B% 

A% 

B% 

A%  IMP  B% 

0 

0 

0 

0 

0 

-1 

0 

-1 

-1 

0 

-1 

-1 

-1 

0 

-1 

-1 

0 

0 

-1 

-1 

0 
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-1 

-1 
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The  operators  XOR  and  EQV  are  logical  complements. 

In  logical  expressions  any  nonzero  value  is  evaluated  as  true,  while  in 
relational  expressions  a  -1  is  generated  as  a  true  value.  Logical  operators 
set  bits  in  the  result  of  the  expression;  any  bit  set  is  a  nonzero  value  and  is 
evaluated  as  true.  For  this  reason,  it  is  important  to  use  logical  operators 
on  the  results  of  relational  expressions  (the  values  of  -1  and  zero)  to  avoid 
unanticipated  results.  In  the  following  example,  the  values  of  A%  and  B% 
both  test  as  true  because  they  are  nonzero  values.  However,  the  logical 
AND  of  these  two  variables  returns  an  unanticipated  result  of  false. 
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Example 

AX  -  2X 
BX  -  4X 

IF  AX  THEN  PRINT  'AX  IS  TRUE' 

IF  BX  THEN  PRINT  'BX  IS  TRUE' 

IF  AX  AND  BX  THEN  PRINT  'AX  AND  BX  IS  TRUE' 

ELSE  PRINT  'AX  AND  BX  IS  FALSE' 

END 

Output 

AX  IS  TRUE 
BX  IS  TRUE 
AX  AND  BX  IS  FALSE 

The  program  returns  this  seemingly  contradictory  result  because  logical 
operators  work  on  the  individual  bits  of  the  operands.  The  8-bit  binary 
representation  of  2%  is  as  follows: 

00000010 

The  8-bit  binary  representation  of  4%  is  as  follows: 

00000100 

Each  value  tests  as  true  because  it  is  nonzero.  However,  the  AND  opera¬ 
tion  on  these  two  values  sets  a  bit  in  the  result  only  if  the  corresponding 
bit  is  set  in  both  operands.  Therefore,  the  result  of  the  AND  operation  on 
4%  and  2%  is  as  follows: 

00000000 

No  bits  are  set  in  the  result,  so  the  value  tests  as  false  (zero). 

If  the  value  of  B%  is  changed  to  6%,  the  resulting  value  tests  as  true 
(nonzero)  because  both  6%  and  2%  have  the  second  bit  set.  Therefore, 
BASIC-PLUS-2  sets  the  second  bit  in  the  result  and  the  value  tests  as 
nonzero  and  true. 

The  8-bit  binary  representation  of  -1  is  as  follows: 

11111111 

The  result  of  -1%  AND  -1%  is  -1%  because  BASIC-PLUS-2  sets  bits  in 
the  result  for  each  corresponding  bit  that  is  set  in  the  operands.  The  result 
tests  as  true  because  it  is  a  nonzero  value. 
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Example 

10  AX  •  -1% 

BX  •  -IX 

20  IF  AX  THEN  PRINT  'AX  IS  TRUE' 

IF  BX  THEN  PRINT  'BX  IS  TRUE' 

IF  AX  AND  BX  THEN  PRINT  'AX  AND  BX  IS  TRUE' 
ELSE  PRINT  'AX  AND  BX  IS  FALSE' 

END 


Output 

AX  IS  TRUE 
BX  IS  TRUE 
AX  AND  BX  IS  TRUE 

Your  program  may  also  return  unanticipated  results  if  you  use  the  NOT 
operator  with  a  nonzero  operand  that  is  not  -1. 

In  the  following  example,  BASIC-PLUS-2  evaluates  both  A%  and  B% 
as  true  because  they  are  nonzero.  NOT  A%  is  evaluated  as  false  (zero) 
because  the  binary  complement  of  -1  is  zero.  NOT  B%  is  evaluated  as 
true  because  the  binary  complement  of  2  has  bits  set  and  is  therefore  a 
nonzero  value. 


Example 

10  AX— IX 

BX»2 

IF  AX  THEN  PRINT  'AX  IS  TRUE' 

ELSE  PRINT  'AX  IS  FALSE' 

END  IF 

IF  BX  THEN  PRINT  'BX  IS  TRUE' 

ELSE  PRINT  'BX  IS  FALSE' 

END  IF 

IF  NOT  AX  THEN  PRINT  'NOT  AX  IS  TRUE' 
ELSE  PRINT  'NOT  AX  IS  FALSE' 

END  IF 

IF  NOT  BX  THEN  PRINT  'NOT  BX  IS  TRUE' 
ELSE  PRINT  'NOT  BX  IS  FALSE' 

END  IF 
END 

Output 

AX  IS  TRUE 
BX  IS  TRUE 
NOT  AX  IS  FALSE 
NOT  BX  IS  TRUE 
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1.6.4  Evaluating  Expressions 


BASIC-PLUS-2  evaluates  expressions  according  to  operator  precedence. 
Each  arithmetic,  relational,  and  string  operator  in  an  expression  has 
a  position  in  the  hierarchy  of  operators.  The  operator's  position  in¬ 
forms  BASIC-PLUS-2  of  the  order  in  which  to  perform  the  operation. 
Parentheses  can  change  the  order  of  precedence. 

Table  1-11  lists  all  operators  as  BASIC-PLUS-2  evaluates  them.  Note  the 
following: 

•  Operators  with  equal  precedence  are  evaluated  logically  from  left  to 
right. 

•  BASIC-PLUS-2  evaluates  expressions  enclosed  in  parentheses  first, 
even  when  the  operator  in  parentheses  has  a  lower  precedence  than 
that  outside  the  parentheses. 

•  The  addition  ( + )  and  multiplication  ( * )  operators  are  evaluated  in 
algebraic  order. 


Table  1—11;  Numeric  Operator  Precedence 


Operator 

Precedence 

**  or  " 

1 

-  (unary  minus)  or  +  (unary  plus) 

2 

*  or  / 

3 

+  or  - 

4 

+  (concatenation) 

5 

all  relational  operators 

6 

NOT 

7 

AND 

8 

OR,  XOR 

9 

IMP 

10 

EQV 

11 
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For  example,  BASIC-PLUS-2  evaluates  the  expression  A  =  15''2  +  12*2  - 
(35  *  8)  in  five  steps: 


Exponentiation  (leftmost  expression) 

Exponentiation 

Addition 

Multiplication 

Subtraction 


1.  15''2  =  225 

2.  12''2  =  144 


3.  225  +  144  =  369 

4.  (35  *  8)  =  280 

5.  369—280  =  89 


There  is  one  exception  to  this  order  of  precedence:  When  an  operator  that 
does  not  require  operands  on  either  side  of  it  (such  as  NOT)  immediately 
follows  an  operator  that  does  require  operands  on  both  sides  (such  as  the 
addition  operator  (+)),  BASIC-PLUS-2  evaluates  the  second  operator  first. 
For  example: 

kl  *  NOT  BX  +  CX 

This  expression  is  evaluated  as  follows: 

(AX  ♦  (NOT  BX))  ♦  cx 

BASIC-PLUS-2  evaluates  the  expression  NOT  B  before  it  evaluates  the 
expression  A  +  NOT  B.  When  the  NOT  expression  does  not  follow  the 
addition  (+)  expression,  the  normal  order  of  precedence  is  followed: 

NOT  AX  +  BX  ♦  cx 

This  expression  is  evaluated  as  follows: 

NOT  ((AX  ♦  BX)  +  c  X) 

BASIC-PLUS-2  evaluates  the  two  expressions  (A%  +  B%)  and  ((A%  + 
B%)  +  C%)  because  the  +  operator  has  a  higher  precedence  than  the  NOT 
operator. 

BASIC-PLUS-2  evaluates  nested  parenthetical  expressions  from  the  inside 
out. 

In  the  following  program,  BASIC-PLUS-2  evaluates  the  parenthetical 
expression  A  quite  differently  from  expression  B.  For  expression  A, 
BASIC-PLUS-2  evaluates  the  innermost  parenthetical  expression  (25  +  5) 
first,  then  the  second  inner  expression  (30  /  5),  then  (6  *  7),  and  finally 
(42  +  3).  For  expression  B,  BASIC-PLUS-2  evaluates  (5  /  5)  first,  then 
(1  *  7),  then  (25  +  7  +  3)  to  obtain  a  different  value. 
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Example 

ICX)  A  *  ((((26  ♦  6)  /  5)  *  7)  +  3) 
PRINT  A 

B*26  +  6/  6*7  +  3 
PRINT  B 

Output 

45 

35 
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Chapter  2 

Environment  Commands 


BASIC-PLUS-2  environment  commands  are  commands  that  you  can  use 
while  in  the  BASIC-PLUS-2  environment.  With  environment  commands, 
you  can  display,  edit,  and  merge  BASIC-PLUS-2  programs,  set  compiler 
defaults,  move  BASIC-PLUS-2  source  programs  to  and  from  storage,  and 
execute  programs.  This  chapter  lists  alphabetically  all  of  the  compiler 
commands  that  you  can  use  within  the  BASIC-PLUS-2  environment.  For 
information  on  immediate  mode  statements,  see  the  BASIC-PLUS-2  User's 
Guide. 
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$  system-command 


$  system-command 

You  can  execute  a  system  command  while  in  the  BASIC-PLUS-2  environ¬ 
ment  by  typing  a  dollar  sign  ( $ )  before  the  command.  BASIC-PLUS-2 
passes  the  command  to  the  operating  system  for  execution.  On  RSX  sys¬ 
tems,  the  context  of  the  BASIC-PLUS-2  environment  and  the  program 
currently  in  memory  do  not  change.  On  RSTS/E  systems,  the  system 
command  executes  and  control  returns  to  the  default  run-time  system,  not 
to  BASIC-PLUS-2. 


Format 

$  system-command 


Syntax  Rules 

None. 


Remarks 


1.  BASIC-PLUS-2  passes  the  system-command  directly  to  the  operating 
system  without  checking  for  validity. 

2.  Your  terminal  displays  any  error  messages  or  output  that  the  com¬ 
mand  generates. 

3.  On  RSX  systems,  control  returns  to  the  BASIC-PLUS-2  environment 
after  the  command  executes.  The  context  (source  file  status,  loaded 
modules,  and  so  on)  of  the  BASIC-PLUS-2  environment  and  the 
program  currently  in  memory  do  not  change  unless  the  command 
causes  the  operating  system  to  abort  BASIC-PLUS-2  or  log  you  out. 

4.  On  RSTS/E  systems,  the  context  of  the  environment  and  the  program 
currently  in  memory  are  lost.  After  the  system  command  executes, 
control  passes  to  monitor  level,  not  to  BASIC-PLUS-2. 
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5.  If  you  have  made  changes  to  the  program  currently  in  memory  and 
enter  a  system  command  without  first  typing  either  the  SCRATCH  or 
REPLACE  command,  BASIC-PLUS-2  displays  the  message  "Unsaved 
change  has  been  made— type  EXIT  or  CTRL/Z  to  exit." 


Example 

BASIC2 

1  DIR  STOCK. B2S 

XUnsaved  change  has  been  made  ■ 

BASIC2 

REPLACE 

BASIC2 

$  DIR  STOCK. B2S 

■  type  EXIT  or  CTRL/Z  to  exit. 
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APPEND 

The  APPEND  command  merges  an  existing  BASIC-PLUS-2  source  pro¬ 
gram  with  the  program  currently  in  memory. 


Format 

APPEND  [file-spec] 

Syntax  Rules 

File-spec  is  the  file  specification  of  the  BASIC-PLUS-2  program  you  want 
to  merge  with  the  program  currently  in  memory.  If  you  do  not  supply  a 
file  type,  the  default  is  B2S. 


Remarks 


1.  If  you  type  APPEND  without  specifying  a  file  name,  BASIC-PLUS-2 
displays  the  following  prompt: 

Append  file  name — 

If  you  do  not  supply  a  file  name  in  response  to  this  prompt, 
BASIC-PLUS-2  searches  for  the  file  NONAME.B2S.  If  NONAME.B2S 
does  not  exist,  BASIC-PLUS-2  signals  the  error  "Can't  find  file  or 
account." 

2.  You  can  append  the  contents  of  file-spec  to  a  source  program  Aat  is 
either  called  into  memory  with  the  OLD  command  or  created  in  the 
BASIC  environment.  If  there  is  no  program  in  memory, 

BASIC-PLUS-2  appends  the  file  to  an  empty  program  with  the  default 
file  name  NONAME. 

3.  If  file-spec  contains  a  BASIC-PLUS-2  line  with  the  same  line  number 
as  a  line  of  the  program  in  memory,  the  line  in  the  appended  file 
replaces  the  line  of  the  program  in  memory  and  BASIC-PLUS-2 
signals  the  warning  "%Duplicate  line  number  n  encountered."  If  no 
line  numbers  are  duplicates,  BASIC-PLUS-2  inserts  the  appended  lines 
into  the  program  in  memory  in  sequential,  ascending  line  number 
order. 
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Example 


4.  The  APPEND  command  does  not  change  the  name  of  the  program  in 
memory. 

5.  If  you  do  not  save  the  appended  version  of  the  program  and  attempt 

to  exit  from  the  BASIC-PLUS-2  environment,  BASIC-PLUS-2  signals 
the  warning  message  "Unsaved  change  has  been  made,  CTRL/Z  or 
EXIT  to  exit."  ' 


BASIC2 

N«w  FIRST_TRY.B2S 
BASIC2 

10  PRINT  "First  program" 

APPEND  NEW_PR0G.B2S 

BASIC2 

LISTNH 

10  PRINT  "First  Program" 

20  PRINT  "This  section  has  been  appended" 
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BRIBES 

The  BRLRES  command  allows  you  to  specify  a  memory-resident  or  user- 
created  library  to  be  used  when  you  task-build  a  program.  When  you 
use  the  BUILD  command,  BASIC-PLUS-2  includes  the  specified  library  in 
the  Task  Builder  command  file.  Your  system  manager  selects  the  default 
library  for  the  BRLRES  command  when  installing  BASIC-PLUS-2. 


Format 

BRLRES  [  lib-param  ] 


Syntax  Rules 

1.  File-spec  is  the  library  file  specification.  The  file  specification  can  either 
be  a  library  supplied  by  BASIC-PLUS-2  or  a  user-created  library. 

2.  NONE  tells  the  Task  Builder  not  to  link  your  task  to  the  default 
memory-resident  library.  Therefore,  the  Task  Builder  links  your  task 
to  the  BASIC-PLUS-2  object  module  library,  BP20TS.0LB. 

3.  If  you  do  not  supply  a  lib-param,  BASIC-PLUS-2  displays  the  follow¬ 
ing  prompt: 

File  spec  [NONE]-- 

If  you  press  the  RETURN  key  in  response  to  this  prompt,  NONE  is 
the  default.  NONE  indicates  that  the  Task  Builder  will  not  link  your 
task  to  the  default  memory-resident  library. 
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Remarks 


1.  BASIC-PLUS-2  supplies  the  following  memory-resident  libraries: 

•  BP2RES 

•  BP2SML 

These  BASIC-PLUS-2  memory-resident  libraries  are  optional.  Your 
system  manager  decides  whether  to  install  them  during  installation. 
For  information  about  the  memory-resident  libraries  available  on  your 
system,  see  your  system  manager. 

2.  The  BUILD  command  includes  the  library  you  specify  with  the 
BRLRES  command  in  the  Task  Builder  command  file.  Therefore, 
you  must  specify  the  BRLRES  command  before  you  specify  the  BUILD 
command  so  the  new  library  specification  is  entered  into  the  Task 
Builder  command  file.  Otherwise,  the  Task  Builder  command  file 
remains  unchanged  and  the  existing  library  in  the  command  file  is 
used. 

3.  The  BRLRES  library  you  specify  remains  in  effect  until  you  either 
specify  a  new  library  with  the  BRLRES  command  or  exit  from  the 
BASIC-PLUS-2  environment.  Once  you  exit  from  the  BASIC-PLUS-2 
environment,  the  default  memory-resident  library  is  used. 

4.  You  can  override  a  library  specified  with  the  BRLRES  command  by 
using  the  /BRLRES  qualifier  to  the  BUILD  command.  The  library  you 
specify  remains  in  effect  only  for  that  particular  build  operation. 

5.  If  you  specify  a  memory-resident  library  that  is  not  available,  the  Task 
Builder  signals  an  error  message. 

6.  For  more  information  on  BASIC-PLUS-2  memory-resident  libraries, 
see  the  BASIC-PLUS-2  User's  Guide. 
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Examples 


Example  1 

!  On  RSX-llM/M-PLUS  Systems 
BRLRES  LB : [1 . 1] BP2RES 

Example  2 

!  On  RSTS/E  Systems 
BRLRES  LB:BASIC2 
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BUILD 


The  BUILD  command  generates  a  command  (CMD)  file  and  an  overlay 
description  language  (ODL)  file  for  the  Task  Builder.  The  CMD  file 
contains  instructions  that  enable  the  Task  Builder  to  link  your  program 
module  or  modules  with  libraries  and  other  routines.  The  ODL  file 
specifies  how  program  segments  should  be  organized  in  memory  during 
program  execution. 


Format 

BUILD  [ prog-nam  [  ,sub-nam,  . 

•  •  ]][ /qualifier  ]  . . . 

Command  Qualifiers 

Defaults 

/BRLRES  sep  lib-param 

See  text. 

/[NO]CLUSTER[  sep  lib-param] 

/NOCLUSTER 

/DSKLIB  sep  file-spec 

See  text. 

/[NOjDUMP 

/NODUMP 

/EXTEND  sep  int-const 

/EXTEND=512 

/[NO]IDS 

/NOIDS 

/[NOjINDEX 

/NOINDEX 

/LIBRARY  sep  lib-param 

See  text. 

/[NOjMAP 

/NOMAP 

/ODLRMS  sep  odi-param 

See  text. 

/[NOjRELATIVE 

/NORELATIVE 

/RMSRES  sep  lib-param 

See  text. 

/[NOjSEQUENTIAL 

/NOSEQUENTIAL 

/[NOJVIRTUAL 

/NOVIRTUAL 

Syntax  Rules 


1.  Prog-nam  is  the  name  of  the  program  you  want  to  build.  If  you  do 
not  specify  a  program,  BASIC-PLUS-2  creates  CMD  and  ODL  files  for 
the  current  program  in  memory,  or  for  NONAME.B2S  if  there  is  no 
current  program  in  memory. 
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2.  Sub-nam  is  the  name  of  the  subprogram  you  want  to  link  to  the  main 
program. 

3.  If  you  specify  a  subprogram  name  you  must  also  specify  a  program 
name. 

4.  The  BUILD  command  line  must  fit  on  a  single  80-character  line. 


Remarks 


1.  The  BUILD  command  does  not  change  the  current  context  of  the 
BASIC-PLUS-2  environment. 

2.  The  BUILD  command  generates  the  CMD  and  ODL  files.  It  does  not 
cause  the  Task  Builder  to  begin  operation. 

•  The  BUILD  command  generates  a  CMD  file  with  the  same  name 
as  the  program  and  a  file  t)rpe  of  CMD. 

•  The  BUILD  command  generates  an  ODL  file  with  the  same  name 
as  the  program  and  a  file  type  of  ODL. 

3.  If  you  do  not  specify  any  BUILD  command  qualifiers,  the  BUILD 
command  accepts  defaults  from  previously  specified  BRLRES,  DSKLIB, 
ODLRMS,  RMSRES,  LIBRARY,  and  SET  commands. 

4.  The  qualifiers  to  the  BUILD  command  tell  the  Task  Builder  to  perform 
special  operations  on  object  modules  when  you  task-build  the  pro¬ 
gram.  You  can  abbreviate  all  qualifiers  to  the  first  three  letters  of  the 
qualifier  keyword. 

5.  When  you  exit  from  the  BASIC-PLUS-2  environment,  all  options  set 
with  qualifiers  return  to  the  system  default  values.  Use  the  SHOW 
command  to  display  your  system  defaults  before  setting  any  qualifiers. 

6.  BASIC-PLUS-2  will  not  cluster  a  BASIC-PLUS-2  memory-resident 
library  when  using  Instruction  and  Data  space  (I-  and  D-Space). 

If  you  attempt  to  use  I-  and  D-Space  and  use  the  BASIC-PLUS-2 
memory-resident  library,  BASIC-PLUS-2  does  not  use  the  library  and 
does  not  signal  an  error. 
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Command  Qualifiers 

/BRLRES  I  ■  I  I  fil^-spec  | 

I  :  /  I  NONE  / 

The  /BRLRES  qualifier  lets  you  specify  a  memory-resident  library  to  be 
linked  to  your  task.  File-spec  can  be  either  a  library  supplied  by 
BASIC-PLUS-2  or  a  user-created  library.  NONE  tells  the  Task  Builder 
not  to  link  your  task  to  the  default  memory-resident  library.  Instead, 
the  Task  Builder  links  your  task  to  BASIC-PLUS-2  object  module  li-' 
brary  BP20TS.0LB.  If  you  do  not  specify  the  /BRLRES  qualifier,  the 
Task  Builder  links  your  task  to  the  current  default  memory-resident  li¬ 
brary  by  default.  See  the  description  of  the  BRLRES  command  for  more 
information. 

/[NOJCLUSTER  [  }  /VO/V£^^  ^ 

The  /CLUSTER  qualifer  causes  the  Task  Builder  to  cluster  memory- 
resident  libraries  to  increase  the  space  available  for  your  task.  Before  you 
use  the  /CLUSTER  qualifier,  at  least  two  memory-resident  libraries  must 
be  linked  to  the  task:  the  BASIC-PLUS-2  memory-resident  library,  and 
one  other  memory-resident  library. 

•  File-spec  specifies  the  memory-resident  library  to  be  clustered.  The 
specified  library  must  be  in  the  account  LB:  on  RSTS/E  systems  or  the 
account  LB:[1,1]  on  RSX  systems. 

•  NONE  specifies  that  only  the  BASIC-PLUS-2  and  RMS-11  libraries  are 
clustered. 

•  /CLUSTER  with  no  argument  causes  the  Task  Builder  to  cluster  the 
default  memory-resident  library.  If  there  is  no  default  cluster  library, 
/CLUSTER  with  no  argument  acts  the  same  as  /CLUSTER.NONE. 

The  /NOCLUSTER  qualifier  tells  the  Task  Builder  not  to  cluster 
memory-resident  libraries  to  increase  the  space  available  for  your  task. 
/NOCLUSTER  is  the  default.  See  the  BASIC-PLUS-2  User's  Guide  for 
more  information  on  using  RMS- 11  libraries. 

/DSKLIB  I'll  file-spec  1 
1  :  /  I  NONE  f 

The  /DSKLIB  qualifier  lets  you  specify  a  disk-resident  object  module 
library  to  be  linked  to  your  program.  File-spec  can  be  either  a  library 
supplied  by  BASIC-PLUS-2  or  a  user-created  library.  NONE  tells  the  Task 
Builder  not  to  link  your  task  to  the  default  object  module  library  If  you 
do  not  specify  the  /DSKLIB  qualifier,  BASIC-PLUS-2  links  your  task  to 
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the  current  default  disk-resident  library.  See  the  description  of  the  DSKLIB 
command  for  more  information. 

/[NOJDUMP 

If  your  program  aborts  with  a  fatal  error,  the  /DUMP  qualifier  causes 
the  Task  Builder  to  generate  a  memory  dump.  The  /NODUMP  quali¬ 
fier  causes  the  Task  Builder  not  to  generate  a  memory  dump  when  the 
program  aborts.  The  default  is  /NODUMP. 

/EXTEND  {  ■  }  int-const 

The  /EXTEND  qualifier  specifies  the  amount  of  space  to  be  added  to  the 
initial  task  size  when  the  task  is  started.  The  Task  Builder  rounds  the 
extension  up  to  the  nearest  32-word  boundary.  The  maximum  allowed 
extension  is  32000.  The  default  is  /EXTEND=512. 

/[NOJIDS 

The  /IDS  qualifier  causes  the  Task  Builder  to  build  your  task  with  1-  and 
D-space  support.  1-  and  D-space  provides  a  faster  program  execution 
time  and  also  allows  you  to  execute  larger  programs  than  usual.  It  is 
recommended  that  you  do  not  use  the  BASlC-PLUS-2  memory-resident 
library  in  an  1-  and  D-space  task.  By  default,  when  you  specify  the  /IDS 
qualifier,  BASIC-PLUS-2  removes  all  references  to  the  BASIC-PLUS- 
2  memory-resident  library  from  the  Task  Builder  command  file.  The 
/NOIDS  qualifier  tells  the  Task  Builder  not  to  build  the  task  with  I-  and 
D-space  support.  /NOIDS  is  the  default.  See  the  BASIC-PLUS-2  User's 
Guide  for  more  information  on  enabling  I-  and  D-space  for  program 
execution. 

[NOJINDEX 

The  /INDEX  qualifier  causes  the  Task  Builder  to  include  the  code 
needed  for  indexed  file  operations.  BASIC-PLUS-2  enables  this  quali¬ 
fier  automatically  for  programs  containing  an  OPEN  statement  with  the 
ORGANIZATION  INDEXED  clause.  If  you  specify  /NOINDEX,  the  Task 
Builder  does  not  include  the  code  needed  for  indexed  file  operations.  The 
default  is  /NOINDEX. 


lib-name 


/LIBRARY  ^  7  M  file-spec 
I  NONE 


The  /LIBRARY  qualifier  lets  you  specify  a  memory-resident  library  to  be 
linked  to  your  program.  File-spec  and  lib-name  can  be  either  a  library 
supplied  with  BASIC-PLUS-2  or  a  user-created  library.  If  you  specify  a 
lib-name  with  no  device,  BASIC-PLUS-2  assumes  LB:  on  RSTS/E  systems 
and  LB:[1,1]  on  RSX  systems.  NONE  tells  the  Task  Builder  not  to  link  your 
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task  to  the  default  memory-resident  library.  Therefore,  the  Task  Builder 
links  to  BASIC-PLUS-2  disk-resident  object  module  library  BP20TS.0LB. 
If  you  do  not  specify  the  /LIBRARY  qualifier,  the  Task  Builder  links  your 
task  to  the  current  default  memory-resident  library.  See  the  description  of 
the  LIBRARY  command  for  more  information. 

/[NOJMAP 

The  /MAP  qualifier  causes  the  Task  Builder  to  generate  an  allocation 
map.  The  /NOMAP  qualifier  causes  the  Task  Builder  to  not  generate  an 
allocation  map.  /NOMAP  is  the  default. 

/ODU,MS{--  } 

The  /ODLRMS  qualifier  lets  you  specify  an  Overlay  Description  Language 
(ODL)  file  for  the  Task  Builder  to  use  when  task-building  your  program. 
The  ODL  file  describes  how  the  Task  Builder  should  overlay  the  task 
in  memory.  When  BASIC-PLUS-2  executes  the  BUILD  command,  the 
ODL  file  is  included  in  the  Task  Builder  command  file.  File-spec  can  be 
either  an  ODL  file  supplied  by  RMS  or  a  user-created  file.  NONE  tells  the 
Task  Builder  not  to  link  your  task  to  the  default  ODL  file.  If  you  do  not 
specify  the  /ODLRMS  qualifier,  the  Task  Builder  uses  the  current  default 
ODL  file  to  task-build  your  program.  See  the  description  of  the  ODLRMS 
command  for  more  information. 

/[NOJRELATIVE 

The  /RELATIVE  qualifier  causes  the  Task  Builder  to  include  the  code 
needed  for  relative  file  operations.  BASIC-PLUS-2  sets  this  qualifier 
automatically  for  programs  containing  an  OPEN  statement  with  the 
ORGANIZATION  RELATIVE  clause.  If  you  specify  /NORELATIVE, 
the  Task  Builder  does  not  include  the  code  necessary  for  relative  file 
operations.  /NORELATIVE  is  the  default. 

/«MS/I£S{  =  } 

The  /RMSRES  qualifier  lets  you  specify  an  RMS  memory-resident  library 
to  be  linked  to  your  program.  The  RMS  library  supplies  RMS  code  for  file 
and  record  operations.  File-spec  can  be  either  a  library  supplied  by  RMS 
or  a  user-created  library.  NONE  tells  the  Task  Builder  not  to  link  your 
task  to  the  default  RMS  library.  Therefore  the  Task  Builder  links  your  task 
to  the  RMS  object  module  library  RMSLIB.OLB.  If  you  do  not  specify  the 
/RMSRES  qualifier,  the  Task  Builder  links  your  task  to  the  current  default 
memory-resident  library.  See  the  description  of  the  RMSRES  command 
for  more  information. 
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/[NO]SEQUENTIAL 

The  /SEQUENTIAL  qualifier  causes  the  Task  Builder  to  include  the 
RMS-11  code  needed  for  sequential  file  operations.  BASIC-PLUS-2  sets 
this  qualifier  automatically  for  programs  containing  an  OPEN  state¬ 
ment  with  the  ORGANIZATION  SEQUENTIAL  clause.  If  you  specify 
/NOSEQUENTIAL,  the  Task  Builder  does  not  include  the  RMS-11  code 
necessary  for  sequential  file  operations.  /NOSEQUENTIAL  is  the  default. 

/[NOJVIRTUAL 

The  /VIRTUAL  qualifier  causes  BASIC-PLUS-2  to  include  the  RMS  code 
needed  for  virtual  array  and  block  I/O  file  operations.  BASIC-PLUS-2 
sets  this  qualifier  automatically  when  you  compile  a  program  containing 
an  OPEN  statement  with  an  ORGANIZATION  VIRTUAL  clause.  If  you 
specify  /NOVIRTUAL,  BASIC-PLUS-2  does  not  include  the  RMS  code 
necessary  for  virtual  array  and  block  I/O  file  operations.  /NOVIRTUAL  is 
the  default. 


Example 


BUILD  MAIN,SUB1.SUB2/DUMP/REL 
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COMPILE 

The  COMPILE  command  converts  a  BASIC-PLUS-2  source  program  to  an 
object  module  and  writes  the  object  file  to  disk. 


Format  COMPILE  [  tile-spec  ]  [ /qualifier  ]  . . . 


Command  Qualifiers 

/BYTE 

/[NOJCHAIN 

/[NOjCROSS-REFERENCE  [  sep  [NOJKEYWORDS  ] 

/[NOJDEBUG 

/DOUBLE 

/[NOJFLAG  sep  [  [NOJDECLINING  ] 

/[NOJLINE 

/[NOjLIST 

/LONG 

/[NOJMACRO 

/[NOjOBJECT 

/PAGE —SIZE  sep  int-const 

/[NOjSCALE  sep  const 

/SINGLE 

/[NOJSYNTAX-CHECK 

/TYPE-DEFAULT  sep  default-clause 

/VARIANT  sep  int-const 

/[NOJWARNINGS 

/WIDTH  sep  int-const 

/WORD 


Defauits 

/WORD 
See  text. 

/NOCROSS-REFERENCE 

/NODEBUG 

/SINGLE 

/FLAG=DECLINING 

/LINE 

/NOLIST 

/WORD 

/NOMACRO 

/OBJECT 

/PAGE_SIZE=60 

/NOSCALE 

/SINGLE 

/NOSYNTAX-CHECK 

/TYPE_DEFAULT=REAL 

/VARIANTS) 

/WARNINGS 

/WIDTH=132 

/WORD 
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Syntax  Rules 


1.  File-spec  is  the  file  specification  of  an  output  file  or  files. 

2.  If  you  do  not  provide  a  file  specification,  the  BASlC-PLUS-2  compiler 
uses  the  name  of  the  program  currently  in  memory  for  the  file  name, 
a  default  file  type  of  OBJ  for  the  object  file,  and  a  default  file  type 

of  LST  for  the  listing  file,  if  a  listing  file  is  requested.  If  a  macro  file 
is  requested,  BASlC-PLUS-2  uses  a  default  file  type  of  MAC  for  the 
macro  source  code  file. 

3.  You  should  not  specify  both  a  file  name  and  file  type.  For  example, 
if  you  enter  the  following  command  line,  BASIC-PLUS-2  creates  only 
the  object  file  and  names  it  NEWOBJ.FIL: 

COMPILE  NEWOBJ.FIL/LIS/OBJ 

4.  File-spec  must  precede  all  qualifiers. 

5.  /Qualifier  specifies  a  qualifier  keyword  that  sets  a  BASIC-PLUS-2 
default. 

6.  You  can  abbreviate  all  positive  qualifiers  to  the  first  three  letters  of  the 
qualifier  keyword.  You  can  abbreviate  a  negative  qualifier  to  NO  and 
the  first  three  letters  of  the  qualifier  ke)word. 

7.  You  cannot  specify  the  /OBJECT  and  /MACRO  qualifiers  together. 


Remarks 


1.  If  you  specify  an  invalid  qualifier,  BASIC-PLUS-2  signals  the  error 
"Illegal  switch,"  and  the  program  does  not  compile.  When  qualifiers 
conflict,  BASIC-PLUS-2  compiles  the  program  using  the  last  specified 
conflicting  qualifier.  For  example,  the  following  command  line  causes 
BASIC-PLUS-2  to  compile  the  program  currently  in  memory  but  does 
not  cause  BASIC-PLUS-2  to  create  an  OBJ  file. 

COHPILE/OBJ/NOOBJ 

2.  If  there  is  no  program  in  memory,  or  the  COMPILE  command  does 
not  execute,  BASIC-PLUS-2  does  not  signal  an  error  or  warning. 
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3.  On  RSX  systems,  if  an  object  file  for  the  program  already  exists  in 
your  directory,  BASIC-PLUS-2  creates  a  new  version  of  the  OBJ  file. 
On  RSTS/E  systems  BASIC-PLUS-2  overwrites  it  with  the  new  object 
file. 

4.  Use  the  COMPILE/NOOBJECT  command  to  check  your  program  for 
errors  without  producing  an  object  file. 

5.  When  you  exit  from  the  BASIC-PLUS-2  environment,  all  options  set 
with  qualifiers  return  to  the  system  default  values.  Use  the  SHOW 
command  to  display  your  system  defaults  before  setting  any  qualifiers. 


Command  Qualifiers 

/BYTE 

The  /BYTE  qualifier  causes  BASIC-PLUS-2  to  allocate  8  bits  of  storage 
as  the  default  for  all  integer  data  not  explicitly  typed  in  the  program. 
Untyped  integer  values  are  treated  as  BYTE  values  and  must  be  in  the 
BYTE  range  or  BASIC-PLUS-2  signals  the  error  "Integer  error  or  overflow." 
Table  1-2  in  this  manual  lists  BASIC-PLUS-2  data  types  and  ranges.  The 
default  is  /WORD. 

/[NOJCHAIN 

The  /CHAIN  qualifer  can  be  used  on  RSTS/E  systems  only.  The  /CHAIN 
qualifier  enables  other  programs  to  CHAIN  into  the  program  using  the 
LINE  clause  of  the  CHAIN  statement.  If  the  program  has  more  than 
200  line  numbers,  the  /NOCHAIN  qualifier  reduces  the  memory  needs 
of  the  output  program  by  disabling  storage  of  line  numbers  in  memory. 
You  cannot  chain  from  one  DECNET  node  to  another.  The  default  is 
determined  at  installation. 

/[NO]CROSS-REFERENCE[  {  "  }  [NOJKEYWORDS  ] 

If  you  use  the  /CROSS-REFERENCE  qualifier  with  the  /LIST  qual¬ 
ifier  when  you  compile  your  program,  the  BASIC-PLUS-2  compiler 
includes  cross-reference  information  in  the  program  listing  file.  If  you 
specify  /CROSS_REFERENCE=KEYWORDS,  BASIC-PLUS-2  also  cross- 
references  BASIC-PLUS-2  ke)words  used  in  the  program.  If  you  specify 
/NOCROSS-REFERENCE,  BASIC-PLUS-2  does  not  include  a  cross 
reference  section  in  the  compiler  listing.  The  default  is  /NOCROSS— 
REFERENCE. 
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/[NOJDEBUG 

The  /DEBUG  qualifier  appends  to  the  object  file  information  on  symbolic 
references  and  line  numbers.  This  information  is  used  by  the 
BASlC-PLUS-2  Debugger  to  debug  your  program.  You  must  specify  the 
/LINE  qualifier  when  you  specify  the  /DEBUG  qualifier  on  the  COMPILE 
command;  otherwise,  BASIC-PLUS-2  signals  an  error. 

When  you  specify  /DEBUG,  control  is  passed  to  the  debugger  when  the 
program  is  executed  in  the  BASIC-PLUS-2  environment.  If  you  specify 
/NODEBUG,  information  on  program  symbols  and  line  numbers  is  not 
included  in  the  object  file  and  control  is  not  passed  to  the  debugger  when 
the  program  executes.  The  default  is  /NODEBUG. 

See  the  BASIC-PLUS-2  User's  Guide  for  more  information  on  using  the 
BASIC-PLUS-2  Debugger. 

/DOUBLE 

The  /DOUBLE  qualifier  causes  BASIC-PLUS-2  to  allocate  64  bits  of 
storage  as  the  default  size  for  all  floating-point  data  not  explicitly  typed 
in  the  program.  Untyped  floating-point  values  are  treated  as  DOUBLE 
values  and  must  be  in  the  DOUBLE  range  or  BASIC-PLUS-2  signals  the 
error  "Floating-point  error  or  overflow."  Table  1-2  in  this  manual  lists 
BASIC-PLUS-2  data  types  and  ranges.  The  default  is  /SINGLE. 

/[NOJFLAG  {  f  }  [NOJDECLINING 

The  /FLAG  qualifier  causes  BASIC-PLUS-2  to  provide  compile-time 
information  about  program  elements  that  are  not  recommended  for  new 
program  development.  For  example,  if  you  specify  the  DECLINING 
clause,  BASIC-PLUS-2  flags  the  following  source  code  as  declining: 

•  CVT$$  (use  EDITS) 

•  CVT$%,  CVTSF,  CVT%$,  CVTF$,  AND  SWAP%  (use  multiple  MAP 
statements) 

•  DEF*  functions  (use  DEF  functions) 

•  FIELD  statements  (use  MAP  DYNAMIC  and  REMAP) 

•  GOTO  line-num%  (do  not  use  the  integer  suffix  with  a  line  number) 

The  default  is  /FLAG=DECLINING. 
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/[NOJLINE 


The  /LINE  qualifier  includes  line  number  information  in  object  modules 
If  you  specify  /NOLINE,  BASIC-PLUS-2  does  not  include  line  number 
information  m  object  modules.  If  you  specify  /NOLINE  in  a  program 
containing  the  run-time  ERL  function,  BASIC-PLUS-2  issues  a  warning 
that  the  /NOLINE  qualifier  has  been  overridden.  The  default  is  /LINE. 


/[NOJUST 

qualifier  causes  BASIC-PLUS-2  to  produce  a  compiler  listing 
file.  The  name  of  the  listing  file  is  the  same  as  the  name  of  the  first  pro¬ 
-am  module  specified,  or  the  name  of  the  program  currently  in  memory 

provided.  The  listing  file  has  a  default  file  type 
of  LST.  If  you  specify  /NOLIST,  BASIC-PLUS-2  does  not  generate  a 
compiler  listing.  /NOLIST  is  the  default. 


/LONG 

The  /LONG  qualifier  causes  BASIC-PLUS-2  to  allocate  32  bits  of  storage 
as  the  default  size  for  all  integer  data  not  explicitly  typed  in  the  program 
Untyped  integer  values  are  treated  as  LONG  values  and  must  be  in 
the  LONG  range  or  BASIC-PLUS-2  signals  the  error  "^Integer  error  or 
overflow."  Table  1-2  in  this  manual  lists  BASIC-PLUS-2  data  types  and 
ranges.  /WORD  is  the  default. 

/[NOJMACRO 

The  /MACRO  qualifier  converts  the  program  into  MACRO-11  source  code 
and  saves  it  in  a  file  with  the  same  name  as  that  of  the  program  and  a 
file  type  of  MAC.  A  MACRO-11  file  can  be  assembled.  If  you  specify 
/NOMACRO,  a  MACRO- 11  source  code  file  is  not  generated.  You  cannot 
/OBJECT  qualifier  with  the  /MACRO  qualifier.  The  default  is 
/NOMACRO. 

/[NOJOBJECT 

The  /OBJECT  qualifier  generates  an  object  module  with  the  same 
hie  name  as  that  of  the  program  and  a  default  file  type  of  OBJ.  The 
/NOOBJECT  qualifier  allows  you  to  check  your  program  for  errors 
wthout  creating  an  object  file.  If  your  program  contains  one  or  more 
object  module  is  not  generated.  You  cannot  specify  the 
/MACRO  qualifier  with  the  /OBJECT  qualifier.  /OBJECT  is  the  default. 


Environment  Commands  2-19 


COMPILE 


/PAGE-SIZE  I  7  }  int-const 


The  /PAGE-SIZE  qualifier  sets  the  page  size  of  the  listing  file.  Int-const 
must  be  greater  than  zero  or  BASIC-PLUS-2  signals  the  warning  message 
'Listing  length  out  of  range — ignored."  The  default  is  /PAGE_SIZE-60. 

/[NOJSCALE  {  ■  }  const 

The  /SCALE  qualifier  allows  control  of  accumulated  round-off  errors 
when  double-precision  numbers  (values  typed  DOUBLE)  are  used. 
Numbers  are  stored  as  multiples  of  10  by  setting  const  (the  scale  factor) 
from  0  through  6.  A  scale  factor  larger  than  6  causes  BASIC-PLUS-2  to 
signal  the  error  message  "Scale  factor  out  of  range-ignored."  /NOSCALE 
is  the  default. 

/SINGLE  .  , 

The  /SINGLE  qualifier  causes  BASIC-PLUS-2  to  allocate  32  bits  of  storage 
as  the  default  size  for  all  floating-point  data  not  explicitly  typed  in  the 
program.  Untyped  floating-point  values  are  treated  as  SINGLE  values 
and  must  be  in  the  SINGLE  range  or  BASIC-PLUS-2  signals  the  error 
"Floating-point  error  or  overflow."  Table  1-2  in  this  manual  lists 
BASIC-PLUS-2  data  types  and  ranges.  The  default  is  /SINGLE. 

/[NOJSYNTAX-CHECK 

The  /SYNTAX-CHECK  qualifier  causes  BASIC-PLUS-2  to  perform  syntax 
checking  after  each  program  line  is  typed.  If  you  specify 
/NOSYNTAX-CHECK,  BASIC-PLUS-2  does  not  perform  syntax  check¬ 
ing.  The  default  is  /NOSYNTAX  _CHECK. 


REAL 

INTEGER 

EXPLICIT 


The  /TYPE —DEFAULT  qualifier  sets  the  default  data  type  (REAL  or 
INTEGER)  for  all  data  not  explicitly  typed  in  your  program  or  specifies 
that  all  data  must  be  explicitly  typed  (EXPLICIT). 

•  REAL  specifies  that  all  data  not  explicitly  typed  is  floating-point  data 
of  the  default  size  (SINGLE  or  DOUBLE). 

•  INTEGER  specifies  that  all  data  not  explicitly  typed  is  integer  data  of 
the  default  size  (BYTE,  WORD,  or  LONG). 

•  EXPLICIT  specifies  that  all  data  in  a  program  must  be  explicitly  typed. 
Implicitly  declared  variables  cause  BASIC-PLUS-2  to  signal  an  error. 

The  default  is  TYPE_DEFAULT=REAL. 
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/VARIANT  I  7  I  int-const 

The  /VARIANT  qualifier  establishes  int-const  as  a  value  to  be  used  in 
compiler  directives.  The  variant  value  can  be  referenced  in  a  lexical 
expression  with  the  lexical  function  %VARIANT.  Int-const  always  has  a 
data  type  of  WORD.  The  default  is  /VARIANT=0. 

/[NOJWARNINGS 

The  /WARNINGS  qualifier  causes  BASIC-PLUS-2  to  display  warning 
messages  during  program  compilation.  The  /NOWARNINGS  qualifier 
causes  BASIC-PLUS-2  to  disable  warning  messages  during  program 
compilation.  The  default  is  /WARNINGS. 

/WIDTH  }  int-const 

The  /WIDTH  qualifier  sets  the  width  of  the  listing  file.  Int-const  must  be 
an  integer  from  72  through  132,  or  BASIC-PLUS-2  signals  the  message 
'Listing  width  out  of  range— ignored."  The  default  is  /WIDTH=132. 

/WORD 

The  /WORD  qualifier  causes  BASIC-PLUS-2  to  allocate  16  bits  of  storage 
as  the  default  for  all  integer  data  not  explicitly  typed  in  the  program. 
Untyped  integer  values  are  treated  as  WORD  values  and  must  be  in 
the  range  -32768  to  32767  or  BASIC-PLUS-2  signals  the  error  message 
"Integer  error  or  overflow."  Table  1-2  in  this  manual  lists  BASIC-PLUS-2 
data  types  and  ranges.  The  default  is  WORD. 


Example 


COMPILE  LETSGO/DOUBLE/LIST 
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The  DELETE  command  removes  a  specified  line  or  range  of  lines  from  the 
program  currently  in  memory. 


Format 


DELETE  line-num  [ 


Syntax  Rules 


The  separator  characters  (comma  or  hyphen)  allow  you  to  delete  individ¬ 
ual  lines  or  a  block  of  lines. 

•  If  you  separate  line  numbers  with  a  comma  ( , ),  BASIC-PLUS-2  deletes 
each  specified  line  number. 

•  If  you  separate  line  numbers  with  a  hyphen  (-),  BASIC-PLUS-2 
deletes  the  inclusive  range  of  lines.  The  lower  line  number  must  be 
specified  first.  If  it  is  not  specified  first,  the  DELETE  command  has  no 
effect. 

•  You  can  combine  individual  line  numbers  and  line  ranges  in  a  single 
DELETE  command.  Note,  however,  that  a  line  number  range  must 
be  followed  by  a  comma  and  not  another  hyphen,  or  BASIC-PLUS-2 
signals  an  error.  The  following  example  deletes  lines  70  through  80, 
line  110,  and  line  124: 

DELETE  70-80,  110,  124 


Remarks 


1.  If  you  do  not  specify  a  line  number,  BASIC-PLUS-2  signals  the  error 
"Illegal  Delete  command." 

2.  BASIC-PLUS-2  signals  an  error  if  there  are  no  lines  in  the  specified 
range  or  if  you  specify  an  illegal  line  number. 
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Examples 

Example  1 

DELETE  60 

Example  2 

DELETE  50,60,90-110 
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DSKLIB 


The  DSKLIB  command  lets  you  select  a  disk-resident,  object  module 
library  to  be  used  when  you  build  your  program.  When  you  use  the 
BUILD  command,  BASIC-PLUS-2  includes  the  specified  library  in  the 
Task  Builder  command  file. 


Format 

DSKLIB  [file-spec] 


Syntax  Rules 


1.  File-spec  can  be  a  disk-resident,  object  module  library  supplied  with 
BASIC-PLUS-2  or  a  user-created  library. 

2.  If  you  specify  the  DSKLIB  command  without  a  file-spec, 
BASIC-PLUS-2  prompts  for  one  and  displays  the  name  of  the  current 
default  disk-resident  library.  If  you  press  the  RETURN  key  without 
specifying  a  library  file  specification,  the  current  default  disk-resident 
library  is  used. 


Remarks 

1.  The  disk-resident  object  module  libraries  supplied  by  BASIC-PLUS-2 
are  as  follows: 

•  LB:[1,1]BP20TS.0LB  (on  RSX  systems) 

•  LB:BP20TS.0LB  (on  RSTS/E  systems) 

Here,  LB:  is  a  RSTS/E  logical  name  for  the  library  account  on  disk. 

The  BASIC-PLUS-2  object  module  libraries  contain  the  Object  Time 
System  (OTS)  files.  If  your  system  does  not  have  memory-resident 
libraries,  the  Task  Bufider  extracts  all  BASIC-PLUS-2  routines  from  the 
disk-resident  object  module  libraries  by  default. 


2-24  Environment  Commands 


DSKLIB 


2.  The  library  you  specify  with  the  DISKLIB  command  is  included  in  all 
Task  Builder  command  files  until  you  either  specify  a  new  library  with 
the  DSKLIB  command  or  exit  from  the  BASIC-PLUS-2  environment. 
Once  you  exit  from  the  BASIC-PLUS-2  environment,  the  default 
object  module  library  set  at  installation  is  restored  as  the  default 
disk-resident  library. 

3.  To  include  the  specified  library  in  the  Task  Builder  command  file,  you 
must  use  the  DSKLIB  command  before  you  use  the  BUILD  command. 

4.  You  can  override  the  DSKLIB  command  with  the  /DSKLIB  qualifier 
to  the  BUILD  command.  The  library  you  specify  remains  in  effect  for 
only  that  particular  build  operation. 

5.  If  you  specify  a  disk-resident  library  that  is  not  available,  the  Task 
Builder  signals  an  error  message. 

6.  See  your  system  manager  for  more  information  about  the 
BASIC-PLUS-2  disk-resident  libraries  available  on  your  system. 

7.  See  the  BASlC-PLUS-2  User's  Guide  for  more  information  on  object 
module  libraries. 


Examples 


Example  1 

I  On  m-llH/H-PLUS  Systems 
DSKLIB  LB; [1,1]BP20TS 

Example  2 

!  On  RSTS/E  Systems 
DSKLIB  LB:BP20TS 
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EDIT 

The  EDIT  command  allows  you  to  edit  individual  program  lines  while 
in  the  BASIC-PLUS-2  environment  by  invoking  an  editor.  EDIT  with  no 
parameters  places  you  in  the  BASIC-PLUS-2  editing  mode,  where  you 
can  enter  BASIC-PLUS-2  editing  mode  commands.  The  BASIC-PLUS-2 
editing  mode  commands  are  described  in  Appendix  C. 


Format 

EDIT  [  [  line-num  [  -line-num  ]  ]  search-clause  [  replace-clause  ]  ] 
search-clause:  delim  unq-strl  delim 
replace-clause:  [  unq-str2  ]  delim  [  int-const  ] 


Syntax  Rules 

1.  Line-num  specifies  the  number  of  the  line  to  be  edited. 

2.  Search-clause  specifies  the  text  you  want  to  remove  or  replace. 

Unq-strl  is  the  search  string  you  want  to  remove  or  replace. 

3.  Replace-clause  specifies  the  replacement  text  and  the  occurrence  of  the 
search  string  you  want  to  replace. 

•  Unq-strl  is  the  replacement  string. 

•  Int-const  specifies  the  occurrence  of  unq-strl  you  want  to  replace. 
If  you  do  not  specify  an  occurrence,  BASIC-PLUS-2  replaces  the 
first  occurrence  of  unq-strl. 

4.  Delim  can  be  any  printing  character  not  used  in  unq-strl  or  unq-strl. 
The  examples  in  this  and  the  following  sections  use  the  slash  ( / )  as  a 
delimiter. 

5.  The  delim  characters  in  search-clause  must  match,  or  BASIC-PLUS-2 
signals  an  error  message. 

6.  The  delim  character  you  use  to  signal  the  end  of  replace-clause  must 
match  the  delim  you  use  in  the  search-clause,  or  BASIC-PLUS-2  does 
not  signal  an  error  and  treats  the  end  delimiter  as  part  of  unq-strl. 
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7.  BASIC-PLUS-2  replaces  or  removes  text  in  a  program  line  as  follows: 

•  If  unq-strl  is  found,  BASIC-PLUS-2  replaces  it  with  uncf-str2. 

•  If  uncf-strl  is  not  found,  BASIC-PLUS-2  signals  an  error. 

•  If  unq-strl  is  null,  BASIC-PLUS-2  replaces  the  first  character  of  the 
last  edited  line  with  uncf-strl  and  does  not  signal  an  error. 

•  If  unq-strl  is  null,  BASIC-PLUS-2  deletes  unq-strl. 

•  BASIC-PLUS-2  matches  and  replaces  strings  exactly  as  you  type 
them.  If  unq-strl  is  uppercase,  BASIC-PLUS-2  searches  for  an 
uppercase  string.  If  it  is  lowercase,  BASIC-PLUS-2  searches  for  a 
lowercase  string. 

8.  If  you  enter  the  EDIT  command  without  an  argument, 

BASIC-PLUS-2  places  you  in  editing  mode,  where  you  can  enter  edit¬ 
ing  mode  commands.  The  BASIC-PLUS-2  editing  mode  commands 
are  as  follows: 

•  DEFINE 

•  EXECUTE 

•  EXIT  or  CTRL/Z 

•  FIND 

•  INSERT 

•  SUBSTITUTE 

See  Appendix  C  for  a  description  of  the  BASIC-PLUS-2  editing  mode 
commands. 

9.  BASIC-PLUS-2  sets  a  specified  line  number  as  the  ciurent  edit  line, 
even  when  the  editing  operation  fails.  That  line  number  remains  set 
as  the  current  edit  line  until  you  specify  another  line  number  or  exit 
from  the  BASIC-PLUS-2  environment. 

10.  You  can  edit  a  range  of  lines  by  separating  two  line  numbers  with 
a  hyphen  (-).  BASIC-PLUS-2  signals  an  error  and  does  not  edit  the 
specified  range  if  there  are  spaces  between  the  h3rphen  and  the  line 
numbers. 

11.  If  you  specify  a  range  of  lines  and  an  occurence,  BASIC-PLUS-2  re¬ 
places  each  occurrence  of  unq-strl  in  each  line  of  the  range  beginning 
with  the  specified  occurrence.  For  example: 
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EDIT 


10  PRINT  DISPLAY# .  DISPUY#,  DISPUY# 
20  PRINT  DISPUYt,  DISPLAY#,  DISPLAY# 
EDIT  10-20  /DISPLAY#/NEW#/2 

10  PRINT  DISPUY#,  NEW#,  NEW# 

20  PRINT  DISPLAY#,  NEW#,  NEW# 

"DISPLAY#"  replaced  by  "NEW#". 

4  substitutions 


Remarks 


1.  BASIC-PLUS-2  displays  the  edited  line  or  lines  with  changes  after 
the  EDIT  command  successfully  executes.  It  also  displays  a  mes¬ 
sage  showing  the  search  string,  replacement  string,  and  number  of 
replacements  made. 

2.  If  you  want  to  edit  a  range  of  numbers,  you  must  specify  both  the 
beginning  and  the  end  of  the  range.  BASIC-PLUS-2  does  not  default 
to  the  last  edited  line  or  to  the  last  line  number  in  the  program. 

3.  When  you  specify  a  line  number  with  no  text  parameters, 
BASIC-PLUS-2  displays  the  message  "Current  edit  line  is  x,"  where  x 
is  the  specified  line  number. 

4.  When  you  type  EDIT  with  no  parameters,  BASIC-PLUS-2  checks  the 
last  edited  line  number  to  make  sure  that  it  still  exists  in  the  current 
program.  If  it  has  been  deleted,  BASIC-PLUS-2  displays  the  error 
"?No  current  line." 


Example 


LIST  100 

100  NEW.STRINGI  *  LEFT$ (STRING!. 12) 

EDIT  100  /LEFT$/RIGHT$/3 

100  NEW.STRINGI  -  RIGHT! (STRING!, 12) 
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EXIT 

The  EXIT  command  or  CTRL/Z  clears  memory  and  returns  control  to  the 
operating  system. 

Format 

EXIT 

Syntax  Rules 

None. 

Remarks 

If  you  forget  to  save  or  replace  your  program  before  attempting  to  exit 
from  the  BASIC-PLUS-2  environment,  BASIC-PLUS-2  signals  the  warning 
'Unsaved  change  has  been  made,  CTRL/Z  or  EXIT  to  exit.'  This  message 
warns  you  that  your  program  will  be  lost  if  you  do  not  use  either  the 
SAVE  or  REPLACE  command  before  exiting.  If  you  do  not  save  or  replace 
the  program  and  exit  from  the  BASIC-PLUS-2  environment,  the  program 
changes  are  lost. 

Example 


EXIT 

XUneaved  change  has  been  made,  CTRL/Z  or  EXIT  to  exit 
BASIC2 
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EXTRACT 


The  EXTRACT  command  extracts  a  specified  line  or  range  of  lines  from 
the  program  currently  in  memory  and  deletes  the  remaining  program 
lines. 


Format 


Syntax  Rules 


1.  The  separator  characters  (comma  or  h)rphen)  allow  you  to  extract 
individual  lines  or  a  range  of  lines  while  deleting  all  others.  All 
extracted  lines  remain  in  memory. 

•  If  you  separate  line  numbers  with  a  comma  ( , ),  BASIC-PLUS-2 
extracts  each  specified  line  number. 

•  If  you  separate  line  numbers  with  a  h)rphen  (-),  BASIC-PLUS-2 
extracts  the  inclusive  range  of  lines.  The  lower  line  number  must 
be  specified  first  or  the  EXTRACT  coinmand  has  no  effect. 

•  You  can  combine  individual  line  numbers  and  line  ranges  in  a 
single  EXTRACT  command.  Note,  however,  that  a  line  number 
range  must  be  followed  by  a  comma  and  not  another  hyphen,  or 
BASlC-PLUS-2  signals  an  error.  The  following  example  extracts 
lines  70  through  80,  line  110,  and  line  124,  and  deletes  the  rest  of 
the  program. 

EXTRACT  70-80,  110,  124 
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Remarks 


EXTRACT 


1.  If  you  do  not  specify  a  line  number,  BASIC-PLUS-2  signals  an  error. 

2.  BASIC-PLUS-2  signals  an  error  if  there  are  no  lines  in  the  specified 
range  or  if  you  specify  an  illegal  line  number. 


Example 


EXTRACT  300  -  1000 
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HELP 

The  HELP  command  displays  online  documentation  for  BASIC-PLUS-2 
commands,  qualifiers,  statements,  functions,  and  conventions. 

Format 

HELP  [unq-str]... 


Syntax  Rules 

1.  Unq-str  is  a  BASIC-PLUS-2  topic,  qualifier,  command,  statement, 
function,  or  convention. 

2.  The  first  unq-str  must  be  one  of  the  topics  described  in  the  HELP  file. 

3.  You  can  specify  a  subtopic  after  the  topic.  Separate  one  unq-str  from 
another  with  a  space. 

4.  You  can  use  the  asterisk  ( * )  wildcard  character  in  unq-str. 
BASIC-PLUS-2  then  matches  any  portion  of  the  specified  topic. 

5.  If  you  type  HELP  with  no  parameters,  BASIC-PLUS-2  displays  a  list 
of  topics  for  you  to  choose  from. 


Remarks 


1.  If  the  unq-str  you  specify  is  not  a  unique  topic  or  subtopic, 
BASIC-PLUS-2  displays  information  on  all  topics  or  subtopics  begin¬ 
ning  with  unq-str. 

2.  An  asterisk  ( * )  indicates  that  you  want  to  display  information  that 
matches  any  portion  of  the  topic  you  specify.  For  example,  if  you  type 
"Help  statements  GO*,"  BASIC-PLUS-2  displays  information  on  the 
GOSUB  statement  and  the  GOTO  statement. 
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HELP 


3.  When  information  on  a  particular  topic  or  subtopic  is  not  available, 
BASIC-PLUS-2  signals  the  message  "Sorry,  no  help  on  that  subject." 

4.  To  exit  from  HELP,  press  the  RETURN  key  until  you  get  the  BASIC2 
prompt. 


Example 


BASIC2 

Help  statements  I  RET  I 
STATEMENTS 
GOSUB 

The  GOSUB  statement  transfers  control  to  a  specified  line  number  or 
label  and  stores  the  location  of  the  GOSUB  statement  for  eventual 
return  from  the  subroutine. 

Format 

{  GO  SUB  > 

{  GOSUB  >  target 

Example 

200  GOSUB  1100 
STATEMENTS 

Press  RETURN  for  more. . . 

GOTO 

The  GOTO  statement  transfers  control  to  a  specified  line  number  or 
label. 

Format 

<  GO  TO  > 

{  GOTO  >  target 

Example 

20  GOTO  200 

Topic?  [ret] 

BASIC2 
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IDENTIFY 

The  IDENTIFY  command  displays  an  identification  header  on  the  con¬ 
trolling  terminal.  The  header  contains  the  name  and  version  number  of 
BASIC-PLUS-2. 


Format 

IDENTIFY 

Syntax  Rules 

None. 


Remarks 

The  message  displayed  by  the  IDENTIFY  command  includes  the  name  of 
the  BASIC-PLUS-2  compiler  and  the  version  number. 


Example 


IDENTIFY 

PDP-11  BASIC-PLUS-2  V2.4-00 
BASIC2 
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INQUIRE 


INQUIRE 


The  INQUIRE  command  is  a  synonym  for  the  HELP  command.  See  the 
HELP  command  for  more  information. 
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LIBRARY 


The  LIBRARY  command  allows  you  to  specify  a  BASIC-PLUS-2  memory- 
resident  or  user-created  library  to  be  used  when  you  task-build  the 
program.  When  you  use  the  BUILD  command,  BASIC-PLUS-2  includes 
the  specified  library  in  the  Task  Builder  command  file.  Your  system 
manager  selects  the  default  library  for  the  LIBRARY  command  when 
installing  BASIC-PLUS-2. 


Format 


LIBRARY  [lib-param] 


lib-param: 


Syntax  Rules 


1.  lib-nam  and  file-spec  can  be  a  memory-resident  library  supplied  by 
BASIC-PLUS-2  or  a  user-created  library. 

2.  If  you  specify  a  lib-nam  with  no  device,  the  default  device  is  LB;  on 
RSTS/E  systems  and  LB:[1,1]  on  RSX  systems. 

3.  NONE  tells  the  Task  Builder  not  to  link  your  task  to  the  default 
memory-resident  library.  Therefore,  the  Task  Builder  links  your 
task  to  the  BASIC-PLUS-2  disk-resident  object  module  library.  The 
BASIC-PLUS-2  object  module  library  is  BP20TS.0LB. 

4.  If  you  specify  the  LIBRARY  command  without  a  lib-param, 
BASIC-PLUS-2  prompts  for  one  and  displays  the  name  of  the  cuwent 
default  memory-resident  library.  If  you  press  the  RETURN  key  in 
response  to  this  prompt,  the  current  default  memory-resident  library  is 
used. 
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LIBRARY 


Remarks 


1.  The  memory-resident  libraries  supplied  by  BASIC-PLUS-2  are  as 
follows: 

•  BP2RES 

•  BP2SML 

Because  memory-resident  libraries  are  optional,  your  system  manager 
can  select  none,  one,  or  both  during  the  BASIC-PLUS-2  installa¬ 
tion.  See  the  BASIC-PLUS-2  User's  Guide  for  information  on  using 
BASIC-PLUS-2  memory-resident  libraries.  See  your  system  manager 
for  information  on  the  memory-resident  libraries  available  on  your 
system. 

2.  On^  RSTS/E  systems,  the  LIBRARY  command  does  not  require  the  LB: 
logical  name.  BASIC-PLUS-2  automatically  searches  this  account  for 
the  memory-resident  library  s3mibol  table. 

3.  On  RSX  systems,  the  LIBRARY  command  automatically  references 
libraries  on  LB:[1,1]  unless  you  specify  another  device  and  directory. 

4.  To  include  the  specified  library  in  the  Task  Builder  command  file, 
you  must  use  the  LIBRARY  command  before  you  use  the  BUILQ 
command. 

5.  The  library  you  specify  is  included  in  all  the  Task  Builder  command 
Hies  until  you  either  specify  a  new  library  with  the  LIBRARY  com¬ 
mand  or  exit  from  the  BASIC-PLUS-2  environment.  When  you  exit 
from  the  BASIC-PLUS-2  environment,  the  memory-resident  library  set 
at  installation  is  restored  as  the  default. 

6.  You  can  override  the  LIBRARY  command  with  the  /LIBRARY  qualifier 
to  the  BUILD  command.  The  library  you  specify  remains  in  effect  for 
only  that  particular  build  operation. 

7.  If  the  specified  library  is  not  available,  the  Task  Builder  signals  an 
error  message. 


Example 


LIBRARY  BP2RES 


Environment  Commands  2-37 


LIST  and  LISTNH 


LIST  and  LISTNH 


The  LIST  command  displays  the  program  lines  of  the  program  currently  in 
memory.  Line  numbers  are  sequenced  in  ascending  order.  The  LISTNH 
command  displays  program  lines  without  the  program  header. 


Format 

LIST[NH]  [[-] line-num ^  |  Une-num  ...  7 7 


Syntax  Rules 


1.  Line-num  specifies  a  line  number. 

2.  A  hyphen  (-)  between  the  LIST  command  and  the  /me-nwm  displays 
all  lines  from  the  beginning  of  the  program  up  to  and  including  the 
line  number  you  specify. 

3.  The  separator  characters  (comma  or  hyphen)  allow  you  to  display 
individual  lines  or  a  block  of  lines. 

•  A  line  number  followed  by  a  comma  ( , )  or  hyphen  ( - )  and  a 
carriage  return,  displays  only  the  specified  line. 

•  If  you  separate  line  numbers  with  commas,  BASIC-PLUS-2  dis¬ 
plays  each  specified  line  number. 

•  If  you  separate  line  numbers  with  hyphens,  BASIC-PLUS-2 
displays  the  inclusive  range  of  lines.  The  lower  line  number  must 
come  first.  If  it  does  not,  LIST  has  no  effect. 

•  If  there  are  no  lines  in  the  specified  range,  BASIC-PLUS-2  signals 
an  error. 

•  You  can  combine  individual  line  numbers  and  line  ranges  in 
a  single  LIST  command.  Note,  however,  that  a  line  number 
range  must  be  followed  by  a  comma  and  not  another  hyphen,  or 
BASIC-PLUS-2  signals  an  error. 
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LIST  and  LISTMH 


Remarks 


1.  The  LIST  command  without  parameters  displays  the  entire  program. 

2.  The  LIST  command  displays  program  lines,  along  with  a  header 
containing  the  program  name,  the  current  time,  and  the  date.  To 
suppress  the  program  header,  type  LISTNH. 

3.  BASIC-PLUS-2  displays  the  source  program  lines  in  the  order  you 
specify  in  the  command  line.  BASIC-PLUS-2  displays  line  100  before 
line  10  if  you  type  LIST  100,10. 


Example 


LIST  200-300 


Output 

200  XIF  XVARIANT  •  2*  XTHEN  XABOBT 
260  XEND  XIF 
300  PRINT  A 
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LOAD 

The  LOAD  command  makes  a  previously  aeated  object  module  or  mod¬ 
ules  available  for  execution  with  the  RUN  command. 


Format 

LOAD  file-spec  [  +  file-spec  ]  . . . 


Syntax  Rules 

File-spec  must  be  the  file  speciHcation  of  a  BASIC-PLUS-2  object  module 
or  BASIC-PLUS-2  signals  an  error.  OBJ  is  the  default  file  type.  If  you 
specify  only  the  file  name,  BASIC-PLUS-2  searches  for  an  OBJ  file  in  the 
current  default  directory. 


Remarks 


1.  Each  device  and  directory  specification  applies  to  all  following  file 
specifications  until  you  specify  a  new  directory  or  device. 

2.  The  LOAD  command  accepts  multiple  device,  directory,  and  file 
specifications. 

3.  BASIC-PLUS-2  does  not  process  the  loaded  object  files  until  you  issue 
the  RUN  command.  Consequently,  errors  in  the  loaded  modules  may 
not  be  detected  until  you  execute  them. 

4.  BASlC-PLUS-2  signals  an  error  in  the  following  cases; 

•  If  the  file  is  not  found 

•  If  the  file  specification  is  not  valid 

•  If  the  file  is  not  a  BASIC-PLUS-2  object  module 

•  If  run-time  memory  is  exceeded 

Errors  do  not  change  the  program  currently  in  memory. 


2-40  Environment  Commands 


LOAD 


5.  The  LOAD  command  clears  all  previously  loaded  object  modules  from 
memory. 

6.  T3rping  the  LOAD  command  does  not  change  the  program  cvurently 
in  memory. 


Example 


LOAD  PR06A  *  PROGB  *  PROGC 
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LOCK 

The  LOCK  command  changes  default  values  for  COMPILE  command 
qualifiers.  It  is  a  synonym  for  the  SET  command.  See  the  SET  command 
for  more  information. 
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niEW 


The  NEW  command  clears  BASIC-PLUS-2  memory  and  allows  you  to 
assign  a  name  to  a  new  program. 


Format 

NEW  [ prog-name  ] 


Syntax  Rules 


1.  Prog-name  is  the  name  of  the  program  you  want  to  create. 

2.  BASIC-PLUS-2  on  RSX  systems  allows  program  names  to  contain  a 
maximum  of  nine  characters.  If  the  program  name  exceeds  nine  char¬ 
acters,  BASIC-PLUS-2  truncates  the  program  name  to  nine  characters 
and  does  not  signal  an  error. 

3.  BASIC-PLUS-2  on  RSTS/E  systems  allows  program  names  to  contain 
a  maximum  of  six  characters.  If  the  program  name  exceeds  six  charac¬ 
ters,  BASIC-PLUS-2  truncates  the  program  name  to  six  characters  and 
does  not  signal  an  error. 

4.  If  you  specify  a  file  type  with  the  program  name,  BASIC-PLUS-2 
ignores  the  file  type  but  does  not  signal  an  error. 


Remarks 


1.  If  you  do  not  specify  a  prog-name,  BASIC-PLUS-2  displays  the  follow¬ 
ing  prompt: 

New  file  name — 

Type  in  a  program  name  and  press  RETURN. 

2.  If  you  do  not  provide  a  program  name  BASIC-PLUS-2  assigns  the  file 
name  NONAME  to  your  program  by  default. 
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NEW 


3.  When  you  t)rpe  the  NEW  command,  the  program  currently  in  memory 
is  cleared.  Program  modules  loaded  with  the  LOAD  command  remain 
unchanged. 


Example 


NEW  PR061 
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ODLRMS 


The  ODLRMS  command  lets  you  specify  an  overlay  description  (ODL)  file 
for  the  Task  Builder  to  use  when  task-building  your  program.  The  ODL 
file  describes  how  the  Task  Builder  should  overlay  your  task  in  memory. 
When  you  use  the  BUILD  command,  BASlC-PLUS-2  includes  the  specified 
ODL  file  in  the  Task  Builder  command  file.  Your  system  manager  selects 
the  default  ODL  file  for  yoiur  system  during  installation. 


Format 

ODLRMS  [  odi-param  ] 


odi-param: 


Syntax  Rules 


1.  File-spec  can  be  an  ODL  file  supplied  by  RMS  or  a  user-created  file. 
Table  2-1  lists  and  describes  the  RMS  ODL  files. 

2.  NONE  tells  the  Task  Builder  not  to  link  yoiur  task  to  any  RMS  ODL 
file. 

3.  If  you  specify  the  ODLRMS  command  without  an  odi-param, 
BASlC-PLUS-2  prompts  you  for  one  and  displays  the  name  of  the 
current  default  ODL  file.  If  you  press  the  RETURN  key  without 
specifying  an  ODL  file,  the  current  default  ODL  file  is  used. 
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ODLRMS 


Remarks 


1.  Because  new  versions  of  RMS  can  change  ODL  file  names,  consult  the 
RMS  distribution  kit  for  current  ODL  names. 

2.  The  default  BASIC-PLUS-2  ODL  files  are  usually  located  in  the 
account  LB:[1,1]  on  RSX  systems  and  LB:  on  RSTS/E  systems.  (On 
RSTS/E  systems,  LB:  is  a  logical  name  for  the  library  account  on  disk.) 
See  your  system  manager  for  more  information. 

3.  The  ODL  file  you  specify  is  included  in  all  Task  Builder  command  files 
until  you  either  specify  a  new  ODLRMS  command  or  exit  from  the 
BASIC-PLUS-2  environment.  When  you  exit  from  the  BASIC-PLUS-2 
environment,  the  ODL  file  set  during  installation  is  restored  as  the 
default. 

4.  You  can  override  the  ODLRMS  command  with  the  /ODL  qualifier  to 
the  BUILD  command.  When  you  use  this  qualifier,  the  ODL  file  you 
specify  remains  in  effect  for  only  that  particular  build  operation. 

5.  See  the  description  of  the  RMSRES  command  to  see  which  ODL  files 
are  required  for  each  RMS  library. 

6.  If  the  ODL  file  you  specify  is  unavailable,  the  Task  Builder  signals  an 
error  message. 

7.  See  the  BASlC-PLUS-2  User's  Guide  for  more  information  on  using  the 
RMS  libraries. 


Table  2-1 :  Overiay  Description  Files 


ODL 

File  Name 

File  Organization 

Sequential  Relative  Indexed 

Type  of 
Library 

Overlay 

Segments 

DAPllX 

Yes 

Yes 

Yes 

Disk 

16 

DAPRLX 

Yes 

Yes 

Yes 

Memory 

None 

RMSllS 

Yes 

Yes 

No 

Disk 

11 

RMS12S 

Yes 

Yes 

No 

Disk 

5 

RMSllX 

Yes 

Yes 

Yes 

Disk 

35 

RMS12X 

Yes 

Yes 

Yes 

Disk 

13 

RMSRLX 

Yes 

Yes 

Yes 

Memory 

None 
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ODLRMS 


Examples 


Example  1 

!  On  RSX-llH/H-PLUS  Systems 
ODLRMS  LB : [1 , 1] RMSRLX . ODL 

Example  2 

!  On  RSTS/E  Systems 
ODLRMS  LB: RMSRLX. ODL 
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OLD 


The  OLD  command  brings  a  previously  created  BASIC-PLUS-2  program 
into  memory. 


Format 

OLD  [  file-spec  ] 

Syntax  Rules 

1.  File-spec  is  the  file  specification  of  the  program. 

2.  If  you  do  not  supply  a  file  specification,  BASIC-PLUS-2  prompts  for 
one.  If  you  do  not  enter  a  file  specification  in  response  to  the  prompt, 
BASIC-PLUS-2  searches  for  a  file  named  NONAME.B2S  in  the  current 
default  directory. 

3.  If  you  do  not  specify  a  file  type,  the  default  file  type  is  B2S. 

Remarks 


1.  If  the  BASIC-PLUS-2  compiler  cannot  find  the  file  you  specify, 
BASIC-PLUS-2  signals  the  error  ‘Can't  find  file  or  account." 

2.  When  the  specified  file  is  found,  it  is  placed  in  memory  and  any 
program  currently  in  memory  is  erased.  If  BASIC-PLUS-2  does  not 
find  the  specified  file,  the  program  currently  in  memory  does  not 
change. 

3.  If  you  specify  a  file  that  does  not  begin  with  a  line  number, 
BASIC-PLUS-2  discards  all  text  up  to  the  first  line  riumber,  brings 
the  file  into  memory,  and  signals  the  error  "Illegal  line  format  or 
missing  continuation  at  line  n."  BASIC-PLUS-2  also  signals  this  error 
if  program  text  begins  in  column  one  without  a  line  number. 

4.  If  a  file  contains  two  lines  with  the  same  line  number, 

BASIC-PLUS-2  signals  the  error  "%Duplicate  line  number  n 
encountered." 
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5.  If  a  file  contains  program  lines  that  are  numbered  out  of  sequential 
order,  BASIC-PLUS-2  signals  the  warning  error  "%Line  number  n 
follows  line  number  n."  BASIC-PLUS-2  includes  the  line,  but  places  it 
in  ascending  numeric  order. 

6.  If  a  program  contains  more  than  32767  characters  associated  with  a 
single  line  number,  BASIC-PLUS-2  signals  the  error  ''?Line  too  long." 

7.  On  RSX  systems,  if  a  program  contains  more  than  132  characters  on  a 
single  line,  BASIC-PLUS-2  signals  the  error  "?Line  too  long." 

8.  On  RSTS/E  systems,  if  a  program  contains  more  than  256  characters 
on  a  single  line,  BASIC-PLUS-2  signals  the  error  "?Line  too  long  or 
invalid  file  format."  A  source  file  you  bring  into  memory  with  the 
OLD  command  must  be  a  RSTS/E  native-mode  file  or  BASIC-PLUS-2 
signals  the  error  "Line  too  long  or  invalid  file  format."  If  the  file  you 
want  to  bring  into  memory  is  an  RMS  file,  you  can  convert  it  before 
bringing  it  into  memory  by  using  the  PIP  command  with  the  /RMS 
qualifier. 


Example 


OLD  CHECK 
BASIC2 
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The  RENAME  command  allows  you  to  assign  a  new  name  to  the  pro¬ 
gram  currently  in  memory.  BASIC-PLUS-2  does  not  write  the  renamed 
program  to  a  file  until  you  save  the  program  with  the  REPLACE  or  SAVE 
command. 


Format 

RENAME  [prog-name] 


Syntax  Rules 


1.  Prog-name  specifies  the  new  program  name. 

2.  BASIC-PLUS-2  on  RSX  systems  allows  program  names  to  contain  a 
maximum  of  nine  characters.  If  the  program  name  exceeds  nine  char¬ 
acters,  BASIC-PLUS-2  truncates  the  program  name  to  nine  characters 
and  does  not  signal  an  error. 

3.  BASIC-PLUS-2  on  RSTS/E  systems  allows  program  names  to  contain 
a  maximum  of  six  characters.  If  the  program  name  exceeds  six  charac¬ 
ters,  BASIC-PLUS-2  truncates  the  program  name  to  six  characters  and 
does  not  signal  an  error. 

4.  If  you  do  not  specify  a  new  program  name  with  the  RENAME  com¬ 
mand,  BASIC-PLUS-2  prompts  you  for  one.  If  you  do  not  specify  a 
program  name  in  response  to  the  prompt,  the  name  of  the  program 
currently  in  memory  remains  unchanged. 

5.  If  you  specify  a  file  type,  BASIC-PLUS-2  ignores  the  file  type,  does 
not  signal  an  error,  and  assigns  the  B2S  file  type  to  the  file  when  you 
save  it. 
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Remarks 


^  must  type  SAVE  or  REPLACE  to  write  the  renamed  program  to  a 
file.  If  you  do  not  type  SAVE  or  REPLACE,  BASIC-PLUS-2  does  not 
save  the  renamed  program. 

2.  The  RENAME  command  does  not  affect  the  original  saved  version  of 
the  program. 


Example 


OLD  TEST 
BASIC2 

RENAME  NEWTEST 
BASIC2 

LIST 

NEWTEST  29-JUL-1986  13:60 

PRINT  "This  program  is  a  simple  test" 


BASIC2 

SAVE 

BASIC2 
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REPLACE 


The  REPLACE  command  writes  the  current  program  to  a  storage  medium. 


Format 

REPLACE  [file-spec] 


Syntax  Rules 

1.  File-spec  is  the  file  specification  of  the  program. 

2.  If  you  do  not  supply  a  file-spec,  BASIC-PLUS-2  writes  the  program 
to  the  default  disk  with  the  file  name  of  the  program  currently  in 
memory. 

•  BASIC-PLUS-2  on  RSX  systems  creates  and  saves  a  new  version  of 
the  file,  incrementing  the  version  number  by  1.  Previous  versions 
of  the  file  remain  unchanged. 

•  BASIC-PLUS-2  on  RSTS/E  systems  overwrites  the  original  version 
of  the  file  with  the  new  version. 


Remarks 


1.  If  you  specify  a  file  specification,  it  does  not  have  to  match  the  file 
specification  of  the  program  currently  in  memory.  You  can  differenti¬ 
ate  a  changed  program  from  the  original  version  by  specifying  a  new 
file  specification. 

2.  The  program  currently  in  memory  does  not  change. 
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Example 

REPLACE  PROGA.NEW 
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RMSRES 


The  RMSRES  command  allows  you  to  specify  an  RMS  memory-resident 
library  for  the  Task  Builder  to  use  when  task-building  your  program.  An 
RMS  library  supplies  RMS  code  for  file  and  record  operations.  When  you 
use  the  BUILD  command,  BASIC-PLUS-2  includes  the  specified  library  m 
the  Task  Builder  command  file.  Your  system  manager  selects  the  default 
RMS  library  for  your  system  during  installation. 


Format 

RMSRES  lib-param 


lib-param: 


Syntax  Rules 


1.  File-spec  can  either  be  an  RMS  memory-resident  library  or  a  user- 
created  resident  library.  Table  2-2  lists  the  RMS  libraries. 

2.  NONE  tells  the  Task  Builder  not  to  link  your  task  to  the  default  RMS 
resident  library.  Therefore  the  Task  Builder  links  your  task  to  the  RMS 
object  module  library  RMSLIB.OLB. 

3.  If  you  do  not  supply  a  lib-param,  BASIC-PLUS-2  prompts  for  one 
and  displays  the  name  of  the  current  default  RMS  library.  If  you 
press  the  RETURN  key  in  response  to  this  prompt,  the  current  default 
memory-resident  library  is  used. 
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Remarks 


1.  On  RSX  systems,  the  RMS  libraries  are  usually  located  in  LB:[1,1].  On 
RSTS/E  systems,  the  RMS  libraries  are  usually  located  on  device  LB:. 
LB:  is  a  logical  name  for  the  library  account  on  disk.  See  your  system 
manager  for  more  information  on  the  location  of  the  RMS  libraries. 

2.  To  include  the  specified  library  in  the  Task  Builder  command  file,  you 
must  use  the  RMSRES  command  before  you  use  the  BUILD  command. 

3.  If  you  use  an  RMS  library  other  than  the  default,  you  must  specify 
one  of  the  RMS  ODL  files  listed  in  Table  2—2.  See  the  description  of 
the  ODLRMS  command  for  more  information. 

4.  The  RMSRES  library  you  specify  is  included  in  all  the  Task  Builder 
command  files  until  you  either  specify  a  new  RMSRES  library  with 
the  RMSRES  command  or  exit  from  the  BASIC-PLUS-2  environment. 
When  you  exit  from  the  BASIC-PLUS-2  environment,  the  RMS  library 
set  at  installation  is  restored  as  the  default. 

5.  You  can  override  the  RMSRES  command  with  the  /RMSRES  qualifier 
to  the  BUILD  command.  The  specified  library  remains  in  effect  for 
only  that  particular  build  operation. 

6.  If  the  specified  library  is  not  available,  the  Task  Builder  signals  an 
error  message. 

See  the  BASIC-PLIIS~2  Usct's  Guide  for  more  information  on  using 
RMS  libraries. 


Table  2— 2:  RMS-11  Libraries 

Library  _ File  Organization 

Name  Sequential  Relative  Indexed 

DAPRES  Yes  Yes  Yes 

RMSLIB  Yes  Yes  Yes 


Type  of 
Library 

Memory 

Disk 


RMSRES  Yes  Yes  Yes  Memory 


ODL  File 
Required 

DAPRLX.ODL 

{RMSllS.ODL  ) 
RMS12S.ODL 
RMSllX.ODL  > 
RMS12X.ODL 
DAPllX.ODL  ) 

RMSRLX.ODL 
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Examples 


Example  1 

!  On  RSX-llM/M-PLUS  Systems 
RMSRES  LB: [1.1] RMSRES 

Example  2 

!  On  RSTS/E  Systems 
RMSRES  LB: RMSRES 
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RUN 

The  RUN  command  allows  you  to  execute  a  program  from  the 
BASIC-PLUS-2  environment  without  first  invoking  the  PDP-11  Task 
Builder  to  construct  an  executable  image.  Support  for  the  RUN  command 
is  an  installation  option.  Use  the  SHOW  command  to  see  whether  your 
system  supports  the  RUN  command.  The  RUNNH  command  is  identical 
to  RUN,  except  that  it  does  not  display  the  program  header,  current  date, 
and  time. 

Format 

RUN[NH]  [  file-spec  ]  [ /qualifier  ]  . 

Command  Qualifiers 

Defaults 

/BYTE 

/WORD 

/[NOJCHAIN 

See  text. 

/[NOJDEBUG 

/NODEBUG 

/DOUBLE 

/SINGLE 

/[NOJFLAG  [  sep  [NOJDECLINING  ] 

/FLAG=DECLINING 

/[NO]LINE 

/LINE 

/LONG 

/WORD 

/[NOJSCALE  sep  const 

/NOSCALE 

/SINGLE 

/SINGLE 

/[NOJSYNTAX -CHECK 

/NOSYNTAX -CHECK 

/TYPE —DEFAULT  sep  default-clause 

/TYPE-DEFAULT=REAL 

/VARIANT  sep  int-const 

/VARIANTS) 

/WORD 

/WORD 

Syntax  Rules 


1.  File-spec  is  the  file  specification  of  the  program  you  want  to  execute. 

2.  If  you  do  not  supply  a  file-spec,  BASIC-PLUS-2  executes  the  program 
currently  in  memory. 
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3.  If  you  specify  only  a  file  name,  BASIC-PLUS-2  searches  for  a  file  with 
a  B2S  file  type  in  the  current  default  directory. 

4.  /Qualifier  specifies  a  qualifier  that  sets  a  BASIC-PLUS-2  default. 


Remarks 


1.  BASIC-PLUS-2  signals  the  warning  message  "No  main  program"  if 
you  do  not  have  a  main  program  in  memory  or  do  not  specify  the  file 
specification  of  a  main  program  with  the  RUN  command. 

2.  When  you  specify  a  file  specification  with  the  RUN  command, 
BASIC-PLUS-2  brings  the  program  into  memory  and  then  executes 
it.  You  do  not  have  to  bring  a  program  into  memory  with  the  OLD 
command  to  run  it.  After  program  execution  is  complete,  the  program 
remains  in  memory. 

3.  If  your  program  calls  a  subprogram,  the  subprogram  must  be  compiled 
and  placed  in  memory  with  the  LOAD  command.  If  your  program 
calls  a  subprogram  that  has  not  been  compiled  and  loaded, 
BASIC-PLUS-2  signals  an  error. 

4.  The  RUN  command  does  not  create  an  object  module  file  or  a  list  file. 

5.  The  RUN  command  executes  a  program  starting  at  the  lowest  line 
number. 

6.  When  BASIC-PLUS-2  encounters  a  STOP  statement,  the  program 
stops  executing. 

—  If  you  used  the  RUN  command  to  execute  the  program, 

BASIC-PLUS-2  displays  a  number  sign  (#)  prompt.  You  can 
then  either  type  the  debugger  command  CONTINUE  to  resume 
program  execution,  or  EXIT  to  end  the  program. 

—  If  you  used  the  RUN  command  with  the  /DEBUG  qualifier  to 
execute  the  program,  control  passes  to  the  BASIC-PLUS-2  debug¬ 
ger.  You  can  then  use  the  BASIC-PLUS-2  debugger  commands 
to  display  and  change  program  values  and  to  analyze  your  pro¬ 
gram.  When  you  are  finished  debugging  your  program,  type  the 
debugger  command  CONTINUE  to  resume  program  execution. 

See  Appendix  B  for  a  description  of  the  BASIC-PLUS-2  debugger 
commands. 

7.  When  you  exit  from  the  BASIC-PLUS-2  environment,  all  options  set 
with  qualifiers  return  to  the  system  default  values.  Use  the  SHOW 
command  to  display  your  system  defaults  before  setting  any  qualifiers. 
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Command  Qualifiers 

/BYTE 

The  /BYTE  qualifier  causes  BASIC-PLUS-2  to  allocate  eight  bits  of  storage 
as  the  default  for  all  integer  data  not  explicitly  typed  in  the  program. 
Untyped  integer  values  are  treated  as  BYTE  values  and  must  be  in  the 
BYTE  range  or  BASIC-PLUS-2  signals  the  error  "Integer  error  or  overflow." 
Table  1-2  in  this  manual  lists  BASIC-PLUS-2  data  types  and  ranges.  The 
default  is  /WORD. 

/[NOJCHAIN 

The  /CHAIN  qualifier  can  be  used  on  RSTS/E  systems  only.  The  /CHAIN 
qualiher  enables  other  programs  to  CHAIN  into  the  program  using  the 
LINE  clause  of  the  CHAIN  statement.  If  the  program  has  more  than 
200  line  numbers,  the  /NOCHAIN  qualifier  reduces  the  memory  needs 
of  the  output  program  by  disabling  storage  of  line  numbers  in  memory. 
You  cannot  chain  from  one  DECNET  node  to  another.  The  default  is 
determined  at  installation. 

/[NOJDEBUG 

The  /DEBUG  qualifier  appends  to  the  object  file  information  on  symbolic 
references  and  line  numbers.  This  information  is  used  by  the 
BASIC-PLUS-2  Debugger  to  debug  your  program.  You  must  specify  the 
/LINE  qualifier  when  you  specify  the  /DEBUG  qualifier  on  the  COMPILE 
command;  otherwise,  BASIC-PLUS-2  signals  an  error. 

When  you  specify  /DEBUG,  control  is  passed  to  the  debugger  when  the 
program  is  executed  in  the  BASIC-PLUS-2  environment.  If  you  specify 
/NODEBUG,  information  on  program  symbols  and  line  numbers  is  not 
included  in  the  object  file  and  control  is  not  passed  to  the  debugger  when 
the  program  executes.  The  default  is  /NODEBUG. 

See  the  BASIC-PLUS-2  User's  Guide  for  more  information  on  using  the 
BASIC-PLUS-2  Debugger. 

/DOUBLE 

The  /DOUBLE  qualifier  causes  BASIC-PLUS-2  to  allocate  64  bits  of 
storage  as  the  default  size  for  all  floating-point  data  not  explicitly  typed 
in  the  program.  Untyped  floating-point  values  are  treated  as  DOUBLE 
values  and  must  be  in  the  DOUBLE  range  or  BASIC-PLUS-2  signals  the 
error  "Floating-point  error  or  overflow."  Table  1-2  in  this  manual  lists 
BASIC-PLUS-2  data  types  and  ranges.  The  default  is  /SINGLE. 
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/[NOJFLAG  {  =  }  [NO]DECUNING 

The  /FLAG  qualifier  causes  BASIC-PLUS-2  to  provide  compile-time 
information  about  program  elements  that  are  not  recommended  for  new 
program  development. 

For  example,  if  you  specify  the  DECLINING  clause,  BASIC-PLUS-2  flags 
the  following  source  code  as  declining: 

•  CVT$$  (use  EDIT$) 

•  CVT$%,  CVT$F,  CVT%$,  CVTF$,  AND  SWAP%  (use  multiple  MAP 
statements) 

•  DEF*  functions  (use  DEF  functions) 

•  FIELD  statements  (use  MAP  DYNAMIC  and  REMAP) 

•  GOTO  line-num%  (do  not  use  the  integer  suffix  with  a  line  number) 

The  default  is  /FLAG=DECLINING. 

/[NOJUNE 

The  /LINE  qualifier  includes  line  number  information  in  object  modules. 
If  you  specify  /NOLINE,  BASIC-PLUS-2  does  not  include  line  number 
information  in  object  modules.  If  you  specify  /NOLINE  in  a  program 
containing  the  run-time  ERL  function,  BASIC-PLUS-2  issues  a  warning 
that  the  /NOLINE  qualifier  has  been  overridden.  The  default  is  /LINE. 

/LONG 

The  /LONG  qualifier  causes  BASIC-PLUS-2  to  allocate  32  bits  of  storage 
as  the  default  size  for  all  integer  data  not  explicitly  typed  in  the  program. 
Untyped  integer  values  are  treated  as  LONG  values  and  must  be  in 
the  LONG  range  or  BASIC-PLUS-2  signals  the  error  "Integer  error  or 
overflow."  Table  1-2  in  this  manual  lists  BASIC-PLUS-2  data  types  and 
ranges.  /LONG  is  the  default. 

/[NO]SCALE  {  7  }  const 

The  /SCALE  qualifier  allows  control  of  accumulated  round-off  errors 
when  double-precision  numbers  (values  typed  DOUBLE)  are  used. 
Numbers  are  stored  as  multiples  of  10  by  setting  const  (the  scale  factor) 
from  0  through  6.  A  scale  factor  larger  than  6  causes  BASIC-PLUS-2  to 
signal  the  error  message  "Scale  factor  out  of  range-ignored."  /NOSCALE 
is  the  default. 
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/SINGLE 

The  /SINGLE  qualifier  causes  BASIC-PLUS-2  to  allocate  32  bits  of  storage 
as  the  default  size  for  all  floating-point  data  not  explicitly  typed  in  the 
program.  Untyped  floating-point  values  are  treated  as  SINGLE  values 
and  must  be  in  the  SINGLE  range  or  BASIC-PLUS-2  signals  the  error 
"Floating-point  error  or  overflow."  Table  1-2  in  this  manual  lists 
BASIC-PLUS-2  data  types  and  ranges.  The  default  is  /SINGLE. 

/[NOJSYNTAX-CHECK 

The  /SYNTAX — CHECK  qualifier  causes  BASIC-PLUS-2  to  perform  syntax 
checking  after  each  program  line  is  typed.  If  you  specify 
/NOSYNTAX —CHECK,  BASIC-PLUS-2  does  not  perform  syntax  check¬ 
ing.  The  default  is  /NOSYNTAX -CHECK. 


(  REAL  ] 

/TYPE-DEFAULT  {  7  | 

1  I  ) 

<  INTEGER  J 

1  EXPLICIT  J 

The  /TYPE— DEFAULT  qualifier  sets  the  default  data  type  (REAL  or 
INTEGER)  for  all  data  not  explicitly  typed  in  your  program  or  specifies 
that  all  data  must  be  explicitly  typed  (EXPLICIT). 

•  REAL  specifies  that  all  data  not  explicitly  typed  is  floating-point  data 
of  the  default  size  (SINGLE  or  DOUBLE). 

•  INTEGER  specifies  that  all  data  not  explicitly  typed  is  integer  data  of 
the  default  size  (BYTE,  WORD,  or  LONG). 

•  EXPLICIT  specifies  that  all  data  in  a  program  must  be  explicitly  typed. 
Implicitly  declared  variables  cause  BASIC-PLUS-2  to  signal  an  error. 

The  default  is  TYPE-DEFAULT=REAL. 

/VARIANT  I  7  }  int-const 

The  /VARIANT  qualifier  establishes  int-const  as  a  value  to  be  used  in 
compiler  directives.  The  variant  value  can  be  referenced  in  a  lexical 
expression  with  the  lexical  function  %VARIANT.  Int-const  always  has  a 
data  type  of  WORD.  The  default  is  /VARIANT=0. 

/WORD 

The  /WORD  qualifier  causes  BASIC-PLUS-2  to  allocate  16  bits  of  storage 
as  the  default  for  all  integer  data  not  explicitly  typed  in  the  program. 
Untyped  integer  values  are  treated  as  WORD  values  and  must  be  in 
the  range  -32768  to  32767  or  BASIC-PLUS-2  signals  the  error  message 
"Integer  error  or  overflow."  Table  1-2  in  this  manual  lists  BASIC-PLUS-2 
data  types  and  ranges.  The  default  is  WORD. 
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Example 


JUL-1986  13:52 


RUN  PROGl 

PROGl  29-, 

1 

3 

6 

10 

BASIC2 

RUNNH  PROGl 

1 

3 

6 

10 

BASIC2 
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SAVE 


The  SAVE  command  writes  the  BASIC-PLUS-2  source  program  currently 
in  memory  to  a  file  on  the  default  or  specified  device. 


Format 

SAVE  [file-spec] 


Syntax  Rules 

1.  File-spec  is  the  file  specification  of  the  program  you  want  to  save. 

2.  If  you  do  not  supply  a  file  specification,  BASIC-PLUS-2  saves  the  file 
with  the  name  of  the  program  currently  in  memory  and  a  file  type  of 
B2S. 

3.  If  you  specify  only  the  file  name,  BASIC-PLUS-2  saves  the  program 
with  the  default  file  type  in  the  current  default  directory. 


Remarks 


1.  If  you  specify  a  file  specification  and  the  file  already  exists, 
BASIC-PLUS-2  signals  the  warning  "File  exists-rename  or  replace." 

2.  BASIC-PLUS-2  stores  the  sorted  program  in  ascending  line  number 
order. 

3.  You  can  store  the  program  on  a  specified  device.  For  example: 

SAVE  DB1:NEWTEST.PR0 

BASIC-PLUS-2  saves  the  file  NEWTEST.PRO  on  disk  DBl:. 
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Example 


SAVE  PROG.SAMP.BSS 
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SCALE 


The  SCALE  command  allows  you  to  control  accumulated  round-off  errors 
by  multiplying  DOUBLE  numeric  values  by  10  raised  to  the  scale  factor, 
truncating  them  to  an  INTEGER  value  and  then  storing  them. 


Format 

SCALE  int-const 


Syntax  Rules 


Int-const  specifies  the  power  of  10  you  want  to  use  as  the  scaling  factor. 

•  Int-const  can  be  an  integer  from  0  through  6. 

•  If  the  specified  value  is  greater  than  6,  BASIC-PLUS-2  signals  the  error 
"Scale  factor  of  n  is  out  of  range,"  where  n  is  the  specified  value. 

•  If  you  do  not  supply  an  int-const,  BASIC-PLUS-2  signals  the  error 
"Illegal  number." 


Remarks 


1.  SCALE  affects  only  values  of  the  data  type  DOUBLE. 

2.  BASIC-PLUS-2  multiplies  values  using  the  scale  factor  you  specify 
and  then  truncates  the  value  at  the  decimal  point.  For  example: 

10  DECLARE  DOUBLE  X 
X  =  "2.488888" 

PRINT  USING  "#.#######" ;X 
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The  value  2.488888  is  rounded  as  follows: 


Scale  Value  Produced  for  2.488888 

0  2.488888 

1  2.4 

2  2.48 

3  2.488 

4  2.4888 

5  2.48888 

6  2.488888 

3.  The  SCALE  command  does  not  improve  accuracy;  however,  it  does 
provide  near  exact  accuracy  for  the  number  of  digits  specified. 


Example 

SCALE  2 
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SCRATCH 


The  SCRATCH  command  clears  any  program  currently  in  memory, 
removes  any  object  files  loaded  with  the  LOAD  command,  and  resets  the 
program  name  to  NONAME. 


Format 

SCRATCH 

Syntax  Rules 

None. 

Remarks 

None. 

Example 


SCRATCH 
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SEQUENCE 


The  SEQUENCE  command  causes  BASIC-PLUS-2  to  automatically  gen¬ 
erate  line  numbers  for  your  program  text.  BASIC-PLUS-2  supplies  line 
numbers  for  your  text  until  you  end  the  procedure  or  reach  the  maximum 
line  number  of  32767. 


Format 

SEQUENCE  [  line-num  ]  [ ,  int-const  ] 

Syntax  Rules 

1.  Line-num  specifies  the  line  number  where  sequencing  begins. 

2.  If  you  do  not  specify  a  line  number,  the  default  is  line  number  100. 

3.  Int-const  specifies  the  line  number  increment  for  your  program.  If  you 
do  not  specify  an  increment,  the  default  is  10. 

Remarks 


1.  If  you  specify  a  line  number  that  already  contains  a  statement,  or  if  the 
sequencing  operation  generates  a  line  number  that  already  contains  a 
statement,  BASIC-PLUS-2  signals  the  error  "Attempt  to  sequence  over 
existing  statement,"  and  returns  to  normal  input  mode. 

2.  Type  your  program  text  in  response  to  the  line  number  prompt;  the 
carriage  return  ends  each  line  and  causes  BASIC-PLUS-2  to  generate  a 
new  line  number. 

3.  If  you  press  CTRL/Z  in  response  to  the  line  number  prompt, 
BASIC-PLUS-2  terminates  the  sequencing  operation  and  prompts  for 
another  command. 

4.  When  the  maximum  line  number  of  32767  is  reached,  BASIC-PLUS-2 
terminates  the  sequencing  process  and  returns  to  normal  input  mode. 

5.  BASIC-PLUS-2  does  not  check  syntax  during  the  sequencing  process. 
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Exampls 


BASIC2 

SEQUENCE  100.10 

100  INPUT  "Enter  a  numeric  value"; AX 
110  IF  AX  =  20 


Environment  Commands  2-69 


SET 


SET 


The  SET  command  allows  you  to  specify  BASlC-PLUS-2  defaults  for 
all  BASIC-PLUS-2  qualifiers.  Qualifiers  control  the  compilation  process 
and  the  run-time  environment.  The  defaults  you  set  remain  in  effect  for 
all  subsequent  operations  until  they  are  reset  or  until  you  exit  from  the 
compiler. 


Format 

SET  [  /qualifier  ]  . . . 

Command  Qualifiers 

/BYTE 

/[NOJCHAIN 

/[NO]CLUSTER[  sep  lib-param] 

/[NO]CROSS_REFERENCE  [  sep  [NOJKEYWORDS  ] 

/[NO]DEBUG 

/DOUBLE 

/[NOPUMP 

/EXTEND  sep  int-const 

/[NO]FLAG  sep  [NOJDECLINING 

/[NO]IDS 

/[NO]INDEX 

/[NOJLINE 

/[NO]LIST 

/LONG 

/[NO]MACRO 

/[NOPBJECT 

/PAGE —SIZE  sep  int-const 

/[NOJRELATIVE 

/[NO]SEQUENTIAL 

/SINGLE 

/[NO]SYNT  AX -CHECK 

/TYPE -DEFAULT  sep  default-clause 

/VARIANT  sep  int-const 


Defaults 

/WORD 
See  text. 

/NOCLUSTER 

/NOCROSS-REFERENCE 

/NODEBUG 

/SINGLE 

/NODUMP 

/EXTEND=512 

/FLAG=DECLINING 

/NOIDS 

/NOINDEX 

/LINE 

/NOLIST 

/WORD 

/NOMACRO 

/OBJECT 

/PAGE-SIZE=60 

/NORELATIVE 

/NOSEQUENTIAL 

/SINGLE 

/NOSYNTAX -CHECK 

/TYPE-DEFAULT=REAL 

/VARIANTS) 
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/[NOJVIRTUAL 
/[NO]W  ARMINGS 
/WIDTH  sep  int-const 
/WORD 


/NOVIRTUAL 

/WARNINGS 

/WIDTH=132 

/WORD 


Syntax  Rules 


1.  /Qualifier  specifies  a  qualifier  keyword  that  sets  a  BASIC-PLUS-2 
default. 

2.  BASIC-PLUS-2  signals  the  error  "Illegal  switch"  if  you  do  not  separate 
multiple  qualifiers  with  commas  (,)  or  slashes  (/).  The  same  error  is 
signaled  if  you  separate  qualifiers  with  a  slash  but  do  not  prefix  the 
first  qualifier  with  a  slash. 


Remarks 


If  you  do  not  specify  any  qualifiers,  BASIC-PLUS-2  resets  all  qualifiers 
except  those  set  with  the  /BRLRES,  /DSKLIB,  /LIBRARY,  /ODLRMS, 
/RMSRES,  or  /EXTEND  qualifiers  to  the  installation  defaults.  The  SCALE 
value  set  with  the  SCALE  command  is  also  not  reset  to  the  installation 
default. 


Command  Qualifiers 

/BYTE 

The  /BYTE  qualifier  causes  BASIC-PLUS-2  to  allocate  eight  bits  of  storage 
as  the  default  for  all  integer  data  not  explicitly  typed  in  the  program 
Untyped  integer  values  are  treated  as  BYTE  values  and  must  be  in  the 
BYTE  range  or  BASIC-PLUS-2  signals  the  error  "Integer  error  or  overflow." 
Table  1-2  in  this  manual  lists  BASIC-PLUS-2  data  types  and  ranees  The 
default  is  /WORD.  ® 

/[NOJCHAIN 

The  /CHAIN  qualifer  can  be  used  on  RSTS/E  systems  only.  The  /CHAIN 
qualifier  enables  other  programs  to  CHAIN  into  the  program  using  the 
LINE  clause  of  the  CHAIN  statement.  If  the  program  has  more  than 
200  line  numbers,  the  /NOCHAIN  qualifier  reduces  the  memory  needs 
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of  the  output  prograiTi  by  disabling  storage  of  line  numbers  in  memory. 
You  cannot  chain  from  one  DECNET  node  to  another.  The  default  is 
determined  at  installation. 

MNOlCLUSTeR  [  {‘  }  I 

The  /CLUSTER  qualifer  causes  the  Task  Builder  to  cluster  memory- 
resident  libraries  to  increase  the  space  available  for  your  task.  Before  you 
use  the  /CLUSTER  qualifier,  at  least  two  memory-resident  libraries  must 
be  linked  to  the  task:  the  BASIC-PLUS-2  memory-resident  library,  and 
one  other  memory-resident  library. 

•  File-spec  specifies  the  memory-resident  library  to  be  clustered.  The 
specified  library  must  be  in  the  account  LB:  on  RSTS/E  systems  or  the 
account  LB:[1,1]  on  RSX  systems. 

•  NONE  specifies  that  only  the  BASIC-PLUS-2  and  RMS-11  libraries  are 
clustered. 

•  /CLUSTER  with  no  argument  causes  the  Task  Builder  to  cluster  the 
default  memory-resident  library.  If  there  is  no  default  cluster  library, 
/CLUSTER  with  no  argument  acts  the  same  as  /CLUSTER:NONE. 

The  /NOCLUSTER  qualifier  tells  the  Task  Builder  not  to  cluster 
memory-resident  libraries  to  increase  the  space  available  for  your  task. 
/NOCLUSTER  is  the  default.  See  the  BASIC-PLUS-2  User’s  Guide  for 
more  information  on  using  RMS-11  libraries. 

/[NO]CROSS-REFERENCE[  }  [NO]KEYWORDS  ] 

If  you  use  the  /CROSS-REFERENCE  qualifier  with  the  /LIST  qual¬ 
ifier  when  you  compile  your  program,  the  BASIC-PLUS-2  compiler 
includes  cross-reference  information  in  the  program  listing  file.  If  you 
specify  /CROSS_REFERENCE=KEYWORDS,  BASIC-PLUS-2  also  cross- 
references  BASIC-PLUS-2  keywords  used  in  the  program.  If  you  specify 
/NOCROSS-REFERENCE,  BASIC-PLUS-2  does  not  include  a  cross  refer¬ 
ence  section  in  the  compiler  listing.  The  default  is 
/NOCROSS-REFERENCE. 

/[NOJDEBUG 

The  /DEBUG  qualifier  appends  to  the  object  file  information  on  symbolic 
references  and  line  numbers.  This  information  is  used  by  the 
BASIC-PLUS-2  Debugger  to  debug  your  program.  You  must  specify  the 
/LINE  qualifier  when  you  specify  the  /DEBUG  qualifier  on  the  COMPILE 
command;  otherwise,  BASIC-PLUS-2  signals  an  error. 
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When  you  specify  /DEBUG,  control  is  passed  to  the  debugger  when  the 
program  is  executed  in  the  BASIC-PLUS-2  environment.  If  you  specify 
/NODEBUG,  infomation  on  program  symbols  and  line  numbers  is  not 
included  in  the  object  file  and  control  is  not  passed  to  the  debugger  when 
the  program  executes.  The  default  is  /NODEBUG. 

See  the  BASIC-PHJS-2  User’s  Guide  for  more  information  on  using  the 
BASIC-PLUS-2  Debugger. 

/DOUBLE 

The  /DOUBLE  qualifier  causes  BASIC-PLUS-2  to  allocate  64  bits  of 
storage  as  the  default  size  for  all  floating-point  data  not  explicitly  typed 
in  the  program.  Untyped  floating-point  values  are  treated  as  DOUBLE 
values  and  must  be  in  the  DOUBLE  range  or  BASIC-PLUS-2  signals  the 
error  "Floating-point  error  or  overflow."  Table  1-2  in  this  manual  lists 
BASIC-PLUS-2  data  types  and  ranges.  The  default  is  /SINGLE. 

/[NOJDUMP 

If  your  program  aborts  with  a  fatal  error,  the  /DUMP  qualifier  causes 
the  Task  Builder  to  generate  a  memory  dump.  The  /NODUMP  quali¬ 
fier  causes  the  Task  Builder  not  to  generate  a  memory  dump  when  the 
program  aborts.  The  default  is  /NODUMP. 

/EXTEND  I  7  }  int-const 

The  /EXTEND  qualifier  specifies  the  amount  of  space  to  be  added  to  the 
initial  task  size  when  the  task  is  started.  The  Task  Builder  rounds  the 
extension  up  to  the  nearest  32-word  boundary.  The  maximum  allowed 
extension  is  32000.  The  default  is  /EXTEND=512. 

/[NOJFLAG  {  =  }  [NOJDECLINING 

The  /FLAG  qualifier  causes  BASIC-PLUS-2  to  provide  compile-time 
information  about  program  elements  that  are  not  recommended  for  new 
program  development. 

For  example,  if  you  specify  the  DECLINING  clause,  BASIC-PLUS-2  flags 
the  following  source  code  as  declining: 

•  CVT$$  (use  EDITS) 

CVT$%,  CVT$F,  CVT%$,  CVTF$,  AND  SWAP%  (use  multiple  MAP 
statements) 

•  DEF*  functions  (use  DEF  functions) 
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•  FIELD  statements  (use  MAP  DYNAMIC  and  REMAP) 

•  GOTO  Iine-num%  (do  not  use  the  integer  suffix  with  a  line  number) 

The  default  is  /FLAG=DECLINING. 


The  /IDS  qualifier  causes  the  Task  Builder  to  build  your  task  with  I-  and 
D-space  support.  I-  and  D-space  provides  a  faster  program  execution 
time  and  also  allows  you  to  execute  larger  programs  than  usual.  It  is 
recommended  that  you  do  not  use  the  BASIC-PLUS-2  memory-resident 
library  in  an  I-  and  D-space  task.  By  default,  when  you  specify  the  /IDS 
qualifier,  BASIC-PLUS-2  removes  all  references  to  the  BASIC-PLUS-2 
memory-resident  library  from  the  Task  Builder  command  file.  The 
/NOIDS  qualifier  tells  the  Task  Builder  not  to  build  the  task  with  I- 
and  D-space  support.  /NOIDS  is  the  default.  See  the  BASlC-PUIS-2 
User’s  Guide  for  more  information  on  enabling  I-  and  D-space  for  program 
execution. 

[NOJINDEX 

The  /INDEX  qualifier  causes  the  Task  Builder  to  include  the  code 
needed  for  indexed  file  operations.  BASIC-PLUS-2  enables  this  quali¬ 
fier  automatically  for  programs  containing  an  OPEN  statement  with  the 
ORGANIZATION  INDEXED  clause.  If  you  specify  /NOINDEX,  the  Task 
Builder  does  not  include  the  code  needed  for  indexed  file  operations.  The 
default  is  /NOINDEX. 

/[NOJLINE 

The  /LINE  qualifier  includes  line  number  information  in  object  modules. 
If  you  specify  /NOLINE,  BASIC-PLUS-2  does  not  include  line  number 
information  in  object  modules.  If  you  specify  /NOLINE  in  a  program 
containing  the  run-time  ERL  function,  BASIC-PLUS-2  issues  a  wamir^ 
that  the  /NOLINE  qualifier  has  been  overridden.  The  default  is  /LINE. 

/[NOJUST  ,  . 

The  /LIST  qualifier  causes  BASIC-PLUS-2  to  produce  a  compiler  listing 
file.  By  default,  the  compiler  listing  generated  by  the  /LIST  qualifier 
contains  a  memory  allocation  map.  The  name  of  the  listing  file  is  the 
same  as  the  name  of  the  first  program  module  specified,  or  the  name 
of  the  program  currently  in  memory  if  no  file  specification  is  provided. 
The  listing  file  has  a  default  file  type  of  LST.  If  you  specify  /NOLIST, 
BASIC-PLUS-2  does  not  generate  a  compiler  listing.  /NOLIST  is  the 
default. 
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/LONG 

The  /LONG  qualifier  causes  BASIC-PLUS-2  to  allocate  32  bits  of  storage 
as  the  default  size  for  all  integer  data  not  explicitly  typed  in  the  program. 
Untyped  integer  values  are  treated  as  LONG  values  and  must  be  in 
the  LONG  range  or  BASIC-PLUS-2  signals  the  error  "Integer  error  or 
overflow."  Table  1-2  in  this  manual  lists  BASIC-PLUS-2  data  types  and 
ranges.  /WORD  is  the  default. 

/[NOJMACRO 

The  /MACRO  qualifier  converts  the  program  into  MACRO- 11  source 
code  and  saves  it  in  a  file  with  the  same  name  as  the  program  and  a 
file  type  of  MAC.  A  MACRO- 11  file  can  be  assembled.  If  you  specify 
/NOMACRO,  a  MACRO-11  source  code  file  is  not  generated.  You  cannot 
specify  the  /OBJECT  qualifier  with  the  /MACRO  qualifier.  The  default  is 
/NOMACRO. 

/[NOJOBJECT 

The  /OBJECT  qualifier  generates  an  object  module  with  the  same 
file  name  as  that  of  the  program  and  a  default  file  type  of  OBJ.  The 
/NOOBJECT  qualifier  allows  you  to  check  your  program  for  errors 
without  creating  an  object  file.  If  your  program  contains  one  or  more 
fatal  errors,  an  object  module  is  not  generated.  You  cannot  specify  the 
/MACRO  qualifier  with  the  /OBJECT  qualifier.  /OBJECT  is  the  default. 

/PAGE— SIZE  I  7  }  int-const 

The  /PAGE_S1ZE  qualifier  sets  the  page  size  of  the  listing  file.  Int-const 
must  be  greater  than  zero  or  BASlC-PLUS-2  signals  the  warning  message 
"Listing  length  out  of  range— ignored."  The  default  is  /PAGE_SIZE=60. 

/[NOJRELATIVE 

The  /RELATIVE  qualifier  causes  the  Task  Builder  to  include  the  code 
needed  for  relative  file  operations.  BASlC-PLUS-2  sets  this  qualifier 
automatically  for  programs  containing  an  OPEN  statement  with  the 
ORGANIZATION  RELATIVE  clause.  If  you  specify  /NORELATIVE, 
the  Task  Builder  does  not  include  the  code  necessary  for  relative  file 
operations.  /NORELATIVE  is  the  default. 

/[NOJSEQUENTIAL 

The  /SEQUENTIAL  qualifier  causes  the  Task  Builder  to  include  the 
RMS- 11  code  needed  for  sequential  file  operations.  BASIC-PLUS-2  sets 
this  qualifier  automatically  for  programs  containing  an  OPEN  state¬ 
ment  with  the  ORGANIZATION  SEQUENTIAL  clause.  If  you  specify 
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/NOSEQUENTIAL,  the  Task  Builder  does  not  include  the  RMS- 11  code 
necessary  for  sequential  file  operations.  /NOSEQUENTIAL  is  the  default. 

/SINGLE 

The  /SINGLE  qualifier  causes  BASlC-PLUS-2  to  allocate  32  bits  of  storage 
as  the  default  size  for  all  floating-point  data  not  explicitly  typed  in  the 
program.  Untyped  floating-point  values  are  treated  as  SINGLE  values 
and  must  be  in  the  SINGLE  range  or  BASIC-PLUS-2  signals  the  error 
"Floating-point  error  or  overflow."  Table  1-2  in  this  manual  lists 
BASIC-PLUS-2  data  types  and  ranges.  The  default  is  /SINGLE. 

/[NOJSYNTAX-CHECK 

The  /SYNTAX_CHECK  qualifier  causes  BASIC-PLUS-2  to  perform  syntax 
checking  after  each  program  line  is  typed.  If  you  specify 
/NOSYNTAX -CHECK,  BASIC-PLUS-2  does  not  perform  syntax  check¬ 
ing.  The  default  is  /NOSYNTAX -CHECK. 


REAL 

INTEGER 

EXPLICIT 


The  /TYPE-DEFAULT  qualifier  sets  the  default  data  type  (REAL  or 
INTEGER)  for  all  data  not  explicitly  typed  in  your  program  or  specifies 
that  all  data  must  be  explicitly  typed  (EXPLICIT). 

•  REAL  specifies  that  all  data  not  explicitly  typed  is  floating-point  data 
of  the  default  size  (SINGLE  or  DOUBLE). 

•  INTEGER  specifies  that  all  data  not  explicitly  typed  is  integer  data  of 
the  default  size  (BYTE,  WORD,  or  LONG). 

•  EXPLICIT  specifies  that  all  data  in  a  program  must  be  explicitly  typed. 
Implicitly  declared  variables  cause  BASIC-PLUS-2  to  signal  an  error. 

The  default  is  TYPE-DEFAULT=REAL. 

/VARIANT  {  "  }  int-const 

The  /VARIANT  qualifier  establishes  int-const  as  a  value  to  be  used  in 
compiler  directives.  The  variant  value  can  be  referenced  in  a  lexical 
expression  with  the  lexical  function  %VARIANT.  Int-const  always  has  a 
data  type  of  WORD.  The  default  is  /VARIANT=0. 

/[NOJVIRTUAL 

The  /VIRTUAL  qualifier  causes  BASIC-PLUS-2  to  include  the  RMS  code 
needed  for  virtual  array  and  block  I/O  file  operations.  BASIC-PLUS-2 
sets  this  qualifier  automatically  when  you  compile  a  program  containing 
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an  OPEN  statement  with  an  ORGANIZATION  VIRTUAL  clause.  If  you 
specify  /NOVIRTUAL,  BASIC-PLUS-2  does  not  include  the  RMS  code 
necessary  for  virtual  array  and  block  I/O  file  operations.  /NOVIRTUAL  is 
the  default. 

/[NOJWARNINGS 

The  /WARNINGS  qualifier  causes  BASIC-PLUS-2  to  display  warning 
messages  during  program  compilation.  The  /NOWARNINGS  qualifier 
causes  BASIC-PLUS-2  to  disable  warning  messages  during  program 
compilation.  The  default  is  /WARNINGS. 

/WIDTH  }mt-const 

The  /WIDTH  qualifier  sets  the  width  of  the  listing  file.  Int-const  must  be 
an  integer  from  72  through  132,  or  BASIC-PLUS-2  signals  the  message 
"Listing  width  out  of  range— ignored."  The  default  is  /WIDTH=132. 

/WORD 

The  /WORD  qualifier  causes  BASIC-PLUS-2  to  allocate  16  bits  of  storage 
as  the  default  for  all  integer  data  not  explicitly  typed  in  the  program. 
Untyped  integer  values  are  treated  as  WORD  values  and  must  be  in 
the  range  -32768  to  32767  or  BASIC-PLUS-2  signals  the  error  message 
"Integer  error  or  overflow."  Table  1-2  in  this  manual  lists  BASIC-PLUS-2 
data  types  and  ranges.  The  default  is  /WORD. 


Examples 


Example  1 

SET  /DOOBLE/BYTE/LIST 

Example  2 

SET  DOUBLE. BYTE, LIST 
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SHOW 


The  SHOW  command  displays  the  current  defaults  for  the  BASIC-PLUS-2 
compiler  on  your  terminal. 


Format 

SHOW 

Syntax  Rules 

None. 

Remarks 

None. 

Example 


SHOW 

PDP-11  BASIC-PLUS-2  V2.4-00  using  EIS  with  run  support 


ENVIRONMENT  INFORMATION: 
Current  edit  line  :  0 
NO  Modules  loaded 
NO  Main  module  loaded 

DEFAULT  DATA  TYPE  INFORMATION: 
Data  type  :  REAL 
Real  size  :  SINGLE 
Integer  size  :  WORD 
Scale  factor  :  0 


RMS  FILE  ORGANIZATION: 

NO  Index 
NO  Relative 
NO  Sequential 
NO  Virtual 

LISTING  FILE  INFORMATION: 

NO  Source 

NO  Cross  Reference 
NO  Keywords 

60  lines  by  132  columns 
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COMPILATION  QUALIFIERS: 
Object 
NO  Macro 
Lines 
Warnings 

NO  Debug  records 
NO  Syntax  checking 
Flag  :  Declining 

Variant  :  0 


BASIC2 


BUILD  QUALIFIERS: 

NO  Dump 

NO  Map 

NO  Cluster 

NO  I-  and  D-Space 

Task  extend  :  512 

RMS  ODL  file  :  LB: [i.l]RMSilX 

BP2  Disk  lib  :  LB: [1.1]V240TS 

RMS  Resident  lib  :  NONE 
BP2  Resident  lib  :  NONE 
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UNSAVE 


The  UNSAVE  command  deletes  a  specified  file  from  storage. 


Format 

UNSAVE  [  file-spec  ] 


Syntax  Rules 

File-spec  is  the  file  specification  of  a  program. 


Remarks 


1.  If  you  supply  only  a  file  name,  BASIC-PLUS-2  deletes  the  file  with 
the  specified  name  and  a  file  type  of  B2S. 

2.  If  you  do  not  supply  a  file  specification,  BASIC-PLUS-2  deletes  the  file 
that  has  the  file  name  of  the  program  currently  in  memory  and  a  file 
type  of  B2S. 

3.  If  you  do  not  supply  a  file  specification  and  do  not  have  a  program  in 
memory,  BASIC-PLUS-2  searches  for  the  default  file  NONAME.B2S. 


Example 


UNSAVE  DB2: CHECK. DAT 
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A  compiler  directive  is  an  instruction  that  causes  BASIC-PLUS-2  to 
perform  a  certain  operation  as  it  translates  the  source  program.  This 
chapter  describes  the  compiler  directives  supported  by  BASIC-PLUS-2. 
Each  compiler  directive  is  listed  and  discussed  alphabetically. 
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%ABORT 


The  %ABORT  directive  tenr\inates  program  compilation  and  displays  a 
fatal  error  message  that  you  can  supply. 


Format 

%AB0RT  [str-lit] 


Syntax  Rules 

1.  Only  a  line  number  or  a  comment  field  can  appear  on  the  same 
physical  line  as  the  %ABORT  directive. 

2.  Str-lit  is  the  error  message  text.  It  must  be  a  string  literal  enclosed  in 
quotation  marks. 


Remarks 


When  BASIC-PLUS-2  encounters  a  %ABORT  directive,  it  stops  the  compi¬ 
lation  and  terminates  the  listing  file  if  a  listing  file  has  been  requested.  If 
you  specified  an  error  message,  BASIC -PLUS-2  displays  the  message  text 
on  your  terminal  screen  and  in  the  compilation  listing. 


Example 


100  XIF  %VARIANT  -  2  XTHEN 

XABORT  "Caiiiiot  compile  with  variant  2" 
XEND  XIF 
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%CROSS 


The  %CROSS  directive  causes  BASIC-PLUS-2  to  resume  accumulating 
cross-reference  information  for  the  listing  file  which  was  previously 
suspended  by  the  %NOCROSS  directive. 


Format 

%CR0SS 

Syntax  Rules 

Only  a  line  number  or  a  comment  field  can  appear  on  the  same  physical 
line  as  the  %CROSS  directive. 


Remarks 


1.  The  %CROSS  directive  has  no  effect  unless  you  request  a  cross- 
reference  section  for  the  compilation  listing  with  the 
/CROSS-REFERENCE  qualifier.  For  more  information  on  listing  file 
format,  see  the  BASIC-PLUS-2  User’s  Guide. 

2.  When  a  cross-reference  section  is  requested,  the  BASIC-PLUS-2  com¬ 
piler  resumes  accumulating  cross-reference  information  immediately 
after  encountering  the  %CROSS  directive. 


Example 

10  XCROSS 
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'/•IDENT 


%IDEniT 

The  %IDENT  directive  lets  you  identify  the  version  of  a  program  module. 
The  identification  text  is  placed  in  the  object  module  and  printed  in  the 
listing  header. 


Format 

%IDENT  str-lit 


Syntax  Rules 

1.  Only  a  line  number  or  a  comment  field  can  appear  on  the  same 
physical  line  as  an  %1DENT  directive. 

2.  Str-lit  is  the  identification  text.  It  must  be  a  string  literal  enclosed  in 
quotation  marks. 

•  The  identification  text  can  consist  of  up  to  six  RAD-50  characters. 

•  If  the  identification  text  contains  more  than  six  RAD-50  characters, 
BASIC-PLUS-2  signals  a  warning  message  and  truncates  the  extra 
characters. 

•  If  the  identification  text  contains  characters  other  than  RAD-50 
characters,  BASIC-PLUS-2  signals  a  warning  message  and  the 
%IDENT  directive  is  ignored. 


Remarks 


1.  The  BASIC-PLUS-2  compiler  inserts  the  identification  text  in  the  first 
31  character  positions  of  the  second  line  on  each  listing  page. 
BASIC-PLUS-2  also  includes  the  identification  text  in  the  object 
module,  if  the  compilation  produces  one,  and  in  the  map  file  created 
by  the  Task  Builder,  if  a  map  file  is  requested. 
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%IDENT 


2.  The  %IDENT  directive  should  appear  at  the  beginning  of  your  pro¬ 
gram  if  you  want  the  identification  text  to  appear  on  the  first  page  of 
your  listing.  If  the  %IDENT  directive  appears  after  the  first  program 
statement,  the  text  will  appear  on  the  next  page  of  the  listing  file. 

3.  You  can  use  the  %IDENT  directive  only  once  in  a  module.  If  you 
specify  more  than  one  %IDENT  directive  in  a  module,  BASIC-PLUS-2 
signals  a  warning  and  uses  the  identification  text  specified  in  the  first 
directive. 

4.  The  default  identification  text  is  a  6-digit  number.  The  first  two  digits 
represent  the  compiler  base  level,  while  the  last  four  digits  represent 
the  month  and  day.  For  example,  the  identification  text  100712 
represents  base  level  10,  and  a  date  of  July  12. 


Example 


40  XIDENT  "VIO" 
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SIF-%THEM-%ELSE-%EMD  %IF 


%IF-%THEM-%ELSE-%END  %IF 

The  %IF-%THEN-%ELSE-%END  %IF  directive  lets  you  conditionally 
include  source  code  or  execute  another  compiler  directive. 


Format 

%IF  lex-exp  %THEN  code  [  %ELSE  code  ]  %END  %IF 


Syntax  Rules 


1.  Lex-exp  is  always  a  WORD  integer. 

2.  Lex-exp  can  be  any  of  the  following: 

•  A  lexical  constant  named  in  a  %LET  directive. 

•  An  integer  literal,  with  or  without  the  percent  sign  suffix. 

•  A  lexical  built-in  function  (%VAR1ANT). 

•  Any  combination  of  the  above,  separated  by  valid  lexical  opera¬ 
tors.  Lexical  operators  include  logical  operators,  relational  opera¬ 
tors,  and  the  arithmetic  operators  for  addition  (+),  subtraction  (-), 
multiplication  (•),  and  division  (/). 

3.  Code  is  BASlC-PLUS-2  program  code.  It  can  be  any  BASIC-PLUS-2 
statement  or  another  compiler  directive,  including  another  %IF  direc¬ 
tive.  You  can  nest  %IF  directives  to  eight  levels. 

4.  The  %IF  directive  can  appear  anywhere  in  a  program  where  a  space  is 
allowed,  except  in  column  one  or  within  a  quoted  string.  This  means 
that  you  can  use  the  %IF  directive  to  make  a  whole  statement,  part  of 
a  statement,  or  a  block  of  statements  conditional. 

5.  %THEN,  %ELSE,  and  %END  %IF  do  not  have  to  be  on  the  same 
physical  line  as  %IF. 
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%IF-%THEN-%ELSE-%END  %IF 


Remarks 


1.  If  lex-exp  is  true,  BASIC-PLUS-2  processes  the  %THEN  clause.  If 
lex-exp  is  false,  BASIC-PLUS-2  processes  the  %ELSE  clause.  If  there 
is  no  %ELSE  clause,  BASIC-PLUS-2  processes  the  %END  %IF  clause. 
The  BASIC-PLUS-2  compiler  includes  statements  in  the  %THEN  or 
%ELSE  clause  in  the  source  program  and  executes  directives  in  order 
of  occurrence. 

2.  You  must  include  the  %END  %IF  clause.  Otherwise,  BASIC-PLUS-2 
assumes  the  remainder  of  the  program  is  part  of  the  last  %THEN 
or  %ELSE  clause  and  signals  the  error  "Missing  %END  %IF"  when 
compilation  ends. 


Example 


100  XIF  (^VARIANT  »  2) 

XTHEN  DECLARE  SINGLE  hourly_pay(100) 

XELSE  XIF  (^VARIANT  *  1) 

%THEN  DECLARE  DOUBLE  8alary_pay(100) 

%ELSE  %AB0RT  "Can't  compile  with  specified  variant" 
%END  %1F 
XEND  y.IF 


PRINT  XIF  (XVARIANT  *  2) 

XTHEN  'Hourly  Wage  Chart' 
GOTO  Hourly_routine 
%ELSE  'Salaried  Wage  Chart' 
GOTO  Salary_routine 
%END  %IF 
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%INCLUDE 


%iniCLUDE 

The  %INCLUDE  directive  lets  you  include  BASlC-PLUS-2  source  text 
from  another  program  file  in  the  current  program  compilation. 


Format 

%INCLUDE  str-lit 


Syntax  Rules 


1.  Only  a  line  number  or  a  comment  field  can  appear  on  the  same 
physical  line  as  the  %1NCLUDE  directive. 

2.  Str-lit  specifies  the  file  to  be  included.  It  must  be  a  string  literal 
enclosed  in  quotation  marks. 

3.  If  you  do  not  specify  a  complete  file  specification,  BASIC-PLUS-2  uses 
the  default  device  and  directory  and  the  file  type  B2S. 


Remarks 


1.  Any  statement  that  appears  after  an  END  statement  inside  an  included 
file  causes  BASIC-PLUS-2  to  signal  an  error. 

2.  The  BASIC-PLUS-2  compiler  includes  the  specified  source  file  in  the 
program  compilation  at  the  point  of  the  %INCLUDE  directive  and 
prints  the  included  code  in  the  program  listing  file  if  the  compilation 
produces  one. 

3.  The  included  file  cannot  contain  line  numbers.  If  it  does, 
BASIC-PLUS-2  signals  the  error  "Line  number  may  not  appear  in 
%INCLUDE  file." 

4.  All  statements  in  the  accessed  file  are  associated  with  the  line  number 
of  the  program  line  that  contains  the  %INCLUDE  directive. 

5.  A  file  accessed  by  %INCLUDE  can  itself  contain  a  %INCLUDE 
directive. 
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%INCLUDE 


6.  All  %IF  directives  in  an  included  file  must  have  a  matching 

%END  %IF  directive  or  BASIC-PLUS-2  signals  the  error  ‘IF  directive 
in  INCLUDE  directive  needs  END  IF  directive  in  same  file." 


Example 


100  XINCLUDE  "CHECKIT" 
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%LET 


%LET 


The  %LET  directive  declares  and  provides  values  for  lexical  constants. 
You  can  use  lexical  constants  only  in  conditional  expressions  in  the 
%1F-%THEN-%ELSE  directive  and  in  lexical  expressions  in  subsequent 
%LET  directives. 


Format 

%LET  %lex-var  =  lex-exp 

Syntax  Rules 

1.  Only  a  line  number  or  a  comment  field  can  appear  on  the  same 

physical  line  as  the  %LET  directive. 

2.  Lex-var  is  the  name  of  a  lexical  variable. 

•  Lexical  variables  are  always  WORD  integers. 

•  The  lexical  variable  must  be  preceded  by  a  percent  sign  ( % )  and 
cannot  end  with  a  dollar  sign  ($ )  or  percent  sign. 

3.  Lex-exp  can  be  any  of  the  following: 

•  A  lexical  variable  named  in  a  previous  %LET  directive. 

•  An  integer  literal,  v«th  or  \vithout  the  percent  sign  suffix. 

•  A  lexical  built-in  function. 

•  Any  combination  of  the  above,  separated  by  valid  lexical  opera¬ 
tors.  Lexical  operators  can  be  logical  operators,  relational  opera¬ 
tors,  and  the  arithmetic  operators  for  addition  ( + ),  subtraction  ( - ), 
multiplication  ( • ),  and  division  ( / ). 
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%LET 


Remarks 

You  cannot  change  the  value  of  a  lexical  variable  within  a  program  unit 
once  it  has  been  named  in  a  %LET  directive.  For  more  information  on 
coding  conventions  see  the  BASIC-PLUS-2  User’s  Guide. 


Example 


too  XLET  XDEBUG.ON  -  1% 


Compiler  Directives  3-11 


%UST 


%LIST 

The  %LIST  directive  causes  the  BASIC-PLUS-2  compiler  to  resume 
accumulating  compilation  information  for  the  program  listing  file  which 
was  previously  suspended  by  the  %NOLIST  directive. 


Format 

%LIST 


Syntax  Rules 

Only  a  line  number  or  a  comment  field  can  appear  on  the  same  physical 
line  as  the  %LIST  directive. 


Remarks 


1.  The  %LIST  directive  has  no  effect  unless  you  requested  a  listing  file. 
For  more  information  on  listing  file  format,  see  the  BASlC-PLUS-2 
User's  Guide. 

2.  As  soon  as  it  encounters  the  %LIST  directive,  the  BASIC-PLUS-2 
compiler  resumes  accumulating  information  for  the  program  listing 
file.  Thus,  the  directive  itself  appears  as  the  next  line  in  the  listing  file. 


Example 


100  XLIST 
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%iyocROss 


'/oNOCROSS 


The  %NOCROSS  directive  causes  the  BASIC-PLUS-2  compiler  to  stop 
accumulating  cross-reference  information  for  the  program  listing  file. 


Format 

%N0CR0SS 


Syntax  Rules 

Only  a  line  number  or  a  comment  field  can  appear  on  the  same  physical 
line  as  the  %NOCROSS  directive. 


Remarks 


1.  The  BASIC-PLUS-2  compiler  stops  accumulating  cross-reference 
information  for  the  program  listing  file  immediately  after  encountering 
the  %NOCROSS  directive. 

2.  The  %NOCROSS  directive  has  no  effect  unless  you  request  a  listing 
file  and  cross-reference  information. 

3.  It  is  recommended  that  you  not  embed  a  %NOCROSS  directive  within 
a  statement.  Embedding  a  %NOCROSS  directive  within  a  statement 
makes  the  accumulation  of  cross-reference  information  unpredictable. 
For  more  information  on  listing  file  format,  see  the  BASIC-PLUS-2 
User's  Guide. 


Example 


100  XNOCROSS 
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%NOUST 


%niOLIST 

The  %NOLIST  directive  causes  the  BASIC-PLUS-2  compiler  to  stop 
accumulating  compilation  information  for  the  program  listing  file. 


Format 

%N0LIST 

Syntax  Rules 

Only  a  line  number  or  a  comment  field  can  appear  on  the  same  physical 
line  as  the  %NOLIST  directive. 


Remarks 


1.  As  soon  as  it  encounters  the  %NOLIST  directive,  the  BASIC-PLUS-2 
compiler  stops  accumulating  information  for  the  program  listing  file. 
Thus,  the  directive  itself  does  not  appear  in  the  listing  file. 

2.  The  %NOLIST  directive  has  no  effect  unless  you  requested  a  listing 
file. 

3.  For  more  information  on  the  listing  file  format,  see  the  BASIC-PLUS-2 
User's  Guide. 


Example 


100  XNOLIST 
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%PAGE 


SPACE 


The  %PAGE  directive  causes  BASIC-PLUS-2  to  begin  a  new  page  in  the 
program  listing  file  immediately  after  the  line  that  contains  the  %PAGE 
directive. 


Format 

%PAGE 


Syntax  Rules 

Only  a  line  number  or  a  comment  field  can  appear  on  the  same  physical 
line  as  the  %PAGE  directive. 

Remarks 

The  %PAGE  directive  has  no  effect  unless  you  request  a  listing  file. 


Example 


100  XPAGE 
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SPRINT 


SPRINT 

The  %PRINT  directive  lets  you  insert  a  message  into  your  source  code 
that  the  BASIC-PLUS-2  compiler  prints  during  compilation. 


Format 

%PRINT  str-lit 

Syntax  Rules 

1.  Only  a  line  number  or  a  comment  field  can  appear  on  the  same 
physical  line  as  the  %PRINT  directive. 

2.  Str-lit  is  the  message  text.  It  must  be  a  string  literal  enclosed  in 
quotation  marks. 


Remarks 


1.  BASIC-PLUS-2  prints  the  specified  message  when  it  encounters  the 
%PRINT  directive. 

2.  The  message  text  you  specify  is  displayed  on  the  terminal  screen  and 
in  the  compilation  listing,  if  a  listing  is  requested. 

3.  %PRINT  causes  an  informational  error  to  be  displayed  on  your 
terminal.  The  informational  message  includes  the  message  text  you 
supply. 
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%PRIMT 


Example 


10  XIF  XDEBUG  •  IX  XTHEN 

XPRINT  "This  Is  a  debug  compilation" 
XEND  XIF 

Output 


Error  on  line  10, 

y,PRINT  "This  is  a  debug  compilation" 

User  PRINT  message:  This  is  a  debug  compilation 
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%SBTTL 


%SBTTL 

The  %SBTTL  directive  lets  you  specify  a  subtitle  for  the  program  listing 
file. 

Format 

%SBTTL 

str-lit 

Syntax  Rules 

1. 

Only  a  line  number  or  a  comment  field  can  appear  on  the  same 
physical  line  as  the  %SBTTL  directive. 

2. 

Str-lit  is  the  subtitle  text.  It  must  be  a  string  literal  enclosed  in  quota¬ 
tion  marks  and  have  no  more  than  48  characters. 

3. 

If  you  specify  more  than  48  characters  in  the  subtitle,  BASIC-PLUS-2 
truncates  the  extra  characters  but  does  not  signal  a  warning  or  error. 

Remarks 


1.  The  specified  subtitle  appears  under  the  title  of  all  pages  of  source 
code  in  the  listing  file  until  the  BASIC-PLUS-2  compiler  encounters 
another  %SBTTL  or  %TITLE  directive.  BASIC-PLUS-2  clears  the  sub¬ 
title  field  before  the  allocation  map  section  of  the  listing  is  generated. 
This  way,  you  only  get  a  subtitle  on  the  listing  pages  that  contain 
source  code. 

2.  Because  BASIC-PLUS-2  associates  a  subtitle  with  a  title,  a  new 
%TITLE  directive  sets  the  current  subtitle  to  the  null  string.  In  this 
case,  no  subtitle  appears  in  the  listing  until  BASIC-PLUS-2  encounters 
another  %SBTTL  directive. 

3.  If  you  want  a  subtitle  to  appear  on  the  first  page  of  your  listing,  the 
%SBTTL  directive  should  appear  at  the  beginning  of  your  program, 
immediately  after  the  %TITLE  directive.  Otherwise,  the  subtitle  will 
start  to  appear  only  on  the  second  page  of  the  listing. 
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SSBTTL 


4.  If  you  want  the  subtitle  to  appear  on  the  page  of  the  listing  that 
contains  the  %SBTTL  directive,  the  %SBTTL  directive  should  follow 
a  %PAGE  directive,  or  follow  a  %TITLE  directive  which  follows  a 
%PAGE  directive. 

5.  The  %SBTTL  directive  has  no  effect  unless  you  request  a  listing  file. 


Example 


100  XTITLE  "Learning  to  Program  in  BASIC-PLUS-2" 
XSBTTL  "Using  FOR-NEXT  Loops" 

REM  THIS  PROGRAM  IS  A  SIMPLE  TEST 
200  DATA  1.  2.  3.  4 


NEXT  1% 
300  END 
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STITLE 


%TITLE 

The  %TITLE  directive  lets  you  specify  a  title  for  the  program  listing  file. 


Format 

%TITLE  str-lit 


Syntax  Rules 


1.  Only  a  line  number  or  a  comment  field  can  appear  on  the  same 
physical  line  as  the  %T1TLE  directive. 

2.  Str-lit  is  the  title  text.  It  must  be  a  string  literal  enclosed  in  quotation 
marks  and  can  have  no  more  than  48  characters. 

3.  If  you  specify  more  than  48  characters  in  the  title,  BASIC-PLUS-2 
truncates  the  extra  characters  but  does  not  signal  a  warning  or  error. 


Remarks 


1.  The  specified  title  appears  on  the  first  line  of  every  page  of  the  listing 
file  until  BASIC-PLUS-2  encounters  another  %TITLE  directive  in  the 
program. 

2.  The  %TITLE  directive  should  appear  on  the  first  line  of  your  program, 
before  the  first  statement,  if  you  want  the  specified  title  to  appear  on 
the  first  page  of  your  listing. 

3.  If  you  want  the  specified  title  to  appear  on  the  page  that  contains  the 
%TITLE  directive,  the  %TITLE  directive  should  immediately  follow  a 
%PAGE  directive. 

4.  Because  BASIC-PLUS-2  associates  a  subtitle  with  a  title,  a  new 
%TITLE  directive  sets  the  current  subtitle  to  the  null  string. 

5.  The  %TITLE  directive  has  no  effect  unless  you  request  a  listing  file. 
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i 


%TITLE 


Example 


100  XTITLE  "Learning  to  Program  in  BASIC-PLOS-2" 
REM  THIS  PROGRAM  IS  A  SIMPLE  TEST 
200  DATA  1.  2.  3.  4 


NEXT  IX 
300  END 
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■/•VARIANT 


%VARIANT 


The  %VARIANT  directive  is  a  built-in  lexical  function  that  allows  you  to 
conditionally  control  program  compilation.  %VARIANT  returns  an  integer 
value  when  you  reference  it  in  a  lexical  expression.  You  set  the  variant 
value  with  the  /VARIANT  qualifier  when  you  compile  the  program  or 
with  the  /VARIANT  qualifier  to  the  SET  command. 


Format 

%VARIANT 


Syntax  Rules 

The  %VARIANT  function  can  appear  only  in  a  lexical  expression. 


Remarks 


The  %VARIANT  function  returns  the  integer  value  specified  with 
/VARIANT  qualifier  to  the  COMPILE,  SET,  or  RUN  commands.  The 
returned  integer  always  has  a  data  type  of  WORD. 


Example 


40  XLET  XRSTS  -  2 
60  XLET  XRSX  «  1 
60  %LET  %VAX  -  0 
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SWRIANT 


70  XIF  XVARIANT  -  XRST8 
XTHEN 


XELSE  XIF  XVARIANT  •  XRSX  OR  XVARIANT  -  XVAX 
XTHEN 


XELSE  XABORT  *Ill«gal  compilation  variant* 
XEND  XIF 

XEND  XIF 
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Chapter  4 

Statements  and  Functions 


This  chapter  provides  reference  material  on  all  of  the  BASIC-PLUS-2 
statements  and  functions.  The  statements  and  functions  are  described  in 
alphabetical  order  and  each  statement  or  function  begins  on  a  separate 
page. 
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ABS 


ABS 


The  ABS  function  returns  a  floating-point  number  that  equals  the  absolute 
value  of  a  specified  floating-point  expression. 

Format 

real-var  =  MS  (real-exp) 


Syntax  Rules 

None. 


Remarks 


1.  The  argument  of  the  ABS  function  must  be  a  real  expression.  When 
the  argument  is  a  real  expression,  BASIC-PLUS-2  returns  a  value 
of  the  same  floating-point  size.  When  the  argument  is  not  a  real 
expression,  BASIC-PLUS-2  converts  the  argument  to  the  default 
floating-point  size  and  returns  a  value  of  the  default  floating-point 
size. 

2.  The  returned  floating-point  value  is  always  greater  than  or  equal  to 
zero.  The  absolute  value  of  zero  is  zero.  The  absolute  value  of  a 
positive  number  equals  that  number.  The  absolute  value  of  a  negative 
number  equals  that  number  multiplied  by  -1. 
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ABS 


Example 


10  G  «  5.1273 

A  *  ABS(-100  *  G) 

B  «  -39 

PRINT  ABS(B).  A 

Output 

39  512.73 
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ABS% 


ABS% 

The  ABS%  function  returns  an  integer  that  equals  the  absolute  value  of  a 
specified  integer  expression. 

Format 

int-var  =  MS%(int-exp} 

Syntax  Rules 

None. 

Remarks 

1.  If  you  specify  a  floating-point  expression  for  int-exp,  BASlC-PLUS-2 
truncates  it  to  an  integer  of  the  default  integer  size. 

2.  The  returned  value  is  always  greater  than  or  equal  to  zero.  The 
absolute  value  of  zero  is  zero.  The  absolute  value  of  a  positive 
number  equals  that  number.  The  absolute  value  of  a  negative  number 
equals  that  number  multiplied  by  -1. 

Exanple 


10  GX  -  6.1273 

A  -  ABSX(-100X  ♦  GX) 
B  -  -39 

PRINT  ABSX(B).  A 

Output 

39  512 
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ASCII 


The  ASCII  function  returns  the  ASCII  value  in  decimal  of  a  string's  first 
character. 


Format 


int-var=  |  |  (str-expj 


Syntax  Rules 

None. 


Remarks 


1.  The  ASCII  value  of  a  null  string  is  zero. 

2.  The  ASCII  function  returns  an  integer  value  of  the  default  size  be¬ 
tween  0  and  255. 


Example 


10  DECLARE  STRING  tlme.out 
time.out  *  "Friday" 
PRINT  ASCII (time.out) 


Output 

70 
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ATM 


The  ATN  function  returns  the  angle  of  a  specified  tangent  in  radians. 


Format 

real-var  =  ATN  (real-exp} 

Syntax  Rules 

None. 

Remarks 


1.  ATN  returns  a  value  from  -PI/2  through  PI/2. 

2.  The  argument  of  the  ATN  function  must  be  a  real  expression.  When 
the  argument  is  a  real  expression,  BASIC-PLUS-2  returns  a  value 

of  the  same  floating-point  size.  When  the  argument  is  not  a  real 
expression,  BASIC-PLUS-2  converts  the  argument  to  the  default 
floating-point  size  and  returns  a  value  of  the  default  floating-point 
size. 


Example 


10  DECLARE  SINGLE  angle.rad,  angle.deg,  T 
INPUT  "Tangent  value" ;T 
angle.rad  =  ATN(T) 

PRINT  "The  smallest  angle  with  that  tangent  is"  ; angle.rad;  "radians" 
angle.deg  *  angle.rad/ (PI/180) 

PRINT  "and";  angle.deg;  "degrees" 

Output 

Tangent  value?  2 

The  smallest  angle  with  that  tangent  is  1.10715  radians 
and  63.435  degrees 
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BUFSIZ 


The  BUFSIZ  function  returns  the  record  buffer  size,  in  bytes,  of  a  specified 
channel. 

Format 

int-var  =  B\ifS\l(chnl-exp) 

Syntax  Rules 

1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number.  You 
cannot  precede  the  chnUexp  with  a  number  sign  (#). 

2.  The  value  assigned  to  int-var  is  a  WORD  integer. 


Remarks 


1.  If  the  specified  channel  is  closed,  BUFSIZ  returns  a  value  of  zero. 

2.  BUFSIZ  of  channel  #0  always  returns  the  current  terminal  width  or,  in 
a  batch  stream,  returns  a  value  of  512. 


Example 


10  DECLARE  LONG  bufler.size 
buller.size  «  BUFSIZ (0) 

PRINT  "Buffer  size  equals" ; buff er.size 

Output 

Buffer  size  equals  132 
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CALL 

The  CALL  statement  transfers  control  to  a  subprogram,  external  function, 
or  other  callable  routine.  You  can  pass  arguments  to  the  routine  and  can 
optionally  specify  passing  mechanisms.  When  the  called  routine  finishes 
executing,  control  returns  to  the  calling  program. 

Format 

CALL  routine  [  pass-mech]  [  ( actual-param ,...)] 

routine:  j 

f  sub-name  1 

[  any  callable  routine  J 

1 

r  BY  VALUE  ) 

pass-mech:  j 

BY  REF  \ 

[  BY  DESC  J 

actual-param:  | 

[  /  f  7  1  1  [pass-mech] 

[  array 

Syntax  Rules 


1.  Routine  is  the  name  of  a  BASIC-PLUS-2  SUB  subprogram  or  another 
callable  program  module.  It  cannot  be  a  variable  name. 

NOTE 

Although  you  can  call  routines  written  in  other  languages, 
BASIC-PLUS-2  supports  calls  only  to  BASIC-PLUS-2 
routines. 
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2.  Pass-mech  specifies  how  arguments  are  passed  to  a  non-BASIC  routine. 

•  Specify  a  BY  REF  pass-mech  after  the  routine  name  if  you  are 
invoking  a  MACRO  subprogram.  If  you  invoke  a  MACRO 
subprogram  but  do  not  specify  BY  REF,  errors  in  the  MACRO 
subprogram  will  not  be  handled  correctly. 

•  Do  not  specify  a  pass-mech  if  you  are  invoking  a  BASIC-PLUS-2 
routine.  If  you  specify  a  pass-mech  when  invoking  a 
BASIC-PLUS-2  routine,  BASIC-PLUS-2  does  not  save  the 
BASIC-PLUS-2  internal  variables  and  the  results  are  unpre¬ 
dictable. 

3.  If  you  do  not  specify  a  pass-mech,  BASIC-PLUS-2  passes  arguments  as 

indicated  in  Table  4-1. 

•  BY  VALUE  specifies  that  BASIC-PLUS-2  passes  the  argument's 
16-bit  value.  Only  BYTE  and  WORD  values  can  be  passed 

BY  VALUE.  BYTE  values  passed  BY  VALUE  are  converted  to 
WORD  values. 

•  BY  REF  specifies  that  BASIC-PLUS-2  passes  the  argument's 
address.  This  is  the  default  for  all  arguments  except  strings  and 
entire  arrays. 

•  BY  DESC  specifies  that  BASIC-PLUS-2  passes  the  address  of  a 
BASIC-PLUS-2  descriptor.  You  can  pass  only  string  values  and 
entire  arrays  by  descriptor.  See  the  BASIC-PLUS-2  User's  Guide  for 
a  description  of  BASIC-PLUS-2  descriptors. 

Table  4-1;  BASIC-PLUS-2  Parameter- Passing  Mechanisms 


Parameter 

BY  VALUE 

BY  REF 

BY  DESC 

Integer  and  Real  Data 

Variables 

Yes^ 

Yes* 

No 

Constants 

Yes^ 

Local 

copy^ 

No 

Expressions 

Yes^ 

Local 

copy^ 

No 

Elements  of  a 
nonvirtual  array 

Yes^ 

Local 

copy^ 

No 

^Specifies  the  default  parameter-passing  mechanism. 


2 

Two  asterisks  indicate  that  the  value  can  have  16  bits,  at  most. 
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Table  4-1  (Cent.):  BASIC-PLUS-2  Parameter- Passing 
Mechanisms 


Parameter 

BY  VALUE 

BY  REF 

BY  DESC 

Integer  and  Real  Data 

Virtual 

Yes^ 

Local 

No 

array  elements 

copy^ 

Yes* 

Nonvirtual 

No 

Yes 

entire  array 

Virtual 

No 

No 

Yes 

entire  array 

String  Data 


Variables 

No 

Yes 

Yes* 

Constants 

No 

Local 

Local 

copy^ 

copy 

Expressions 

No 

Local 

copy 

Local 

copy^ 

Nonvirtual 

No 

Local 

Local 

array  elements 

copy 

copy 

Virtual 

No 

Local 

Local 

copy^ 

array  elements 

copy 

Nonvirtual 
entire  arrays 

No 

Yes 

Yes^ 

Yes^ 

Virtual 
entire  arrays 

No 

No 

Other  Parameters 

RFA  variables 

No 

Yes^ 

No 

^Specifies  the  default  parameter-passing 

mechanism. 

^Two  asterisks  indicate  that  the  value  can  have  16  bits,  at  most. 

4.  If  you  call  a  non-BASIC  routine  and  a  passing  mechanism  appears  be¬ 
fore  the  parameter  list,  it  applies  to  all  arguments  passed  to  the  called 
routine  and  the  routine  is  called  with  the  R5  (fifth  register)  calling 
sequence.  You  can  override  this  passing  mechanism  by  specifying  a 
pass-mech  for  individual  arguments  in  the  actual-param  list. 
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5.  Actual-param  lists  the  arguments  to  be  passed  to  the  called  routine. 

6.  You  can  pass  expressions  or  entire  arrays.  Optional  commas  in 
parentheses  after  the  array  name  specify  the  dimensions  of  the  array. 
The  number  of  commas  is  equal  to  the  number  of  dimensions  - 

1.  Thus,  no  comma  specifies  a  one-dimensional  array,  one  comma 
specifies  a  two-dimensional  array,  two  commas  specify  a  three- 
dimensional  array,  and  so  on. 

7.  You  cannot  pass  entire  virtual  arrays.  Instead,  share  the  data  in  a 
virtual  array  between  a  calling  program  and  a  subprogram  by  opening 
a  virtual  file  in  either  program  and  dimensioning  the  array  (using  the 
same  channel  number)  in  both  programs. 

8.  The  name  of  the  routine  can  consist  of  one  through  six  characters  and 
must  conform  to  the  following  rules: 

•  The  first  character  of  an  unquoted  name  must  be  an  alphabetic 
character  (A  through  Z).  The  remaining  characters,  if  present,  can 
be  any  combination  of  letters,  digits  (0  through  9),  dollar  signs 

( $ ),  or  periods  ( . ). 

•  A  quoted  name  can  consist  of  any  combination  of  alphabetic 
characters,  digits,  dollar  signs  ( $ ),  periods  ( . ),  or  spaces. 

•  The  routine  can  be  a  BASIC-PLUS-2  subprogram  or  a  subprogram 
written  in  another  language. 

•  BASIC-PLUS-2  allows  you  to  pass  up  to  32  parameters  to  a 
BASIC-PLUS-2  subprogram  and  up  to  255  parameters  to  a 
MACRO- 11  subprogram. 


Remarks 


1.  BASIC-PLUS-2  does  not  allow  recursion.  That  is,  once  a  subprogram 
is  called,  it  cannot  be  called  again  until  the  SUBEND  or  SUBEXIT 
statement  for  that  routine  has  executed  or  until  an  error  has  been 
trapped  with  ON  ERROR  GO  BACK. 

2.  You  can  specify  a  null  argument  as  an  actuaUparam  for  non-BASIC 
routines  by  omitting  the  argument  and  the  pass-mech,  but  not  the 
commas  or  parentheses.  This  forces  BASIC-PLUS-2  to  pass  a  null 
argument  and  allows  you  to  access  system  routines  from 
BASIC-PLUS-2. 

3.  Arguments  in  the  actuaUparam  list  must  agree  in  data  type  and 
number  with  the  formal  parameters  specified  in  the  subprogram. 
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4.  An  argument  is  modifiable  when  changes  to  it  are  evident  in  the 
calling  program.  Changing  a  modifiable  parameter  in  a  subprogram 
means  the  parameter  is  changed  for  the  calling  program  as  well.  Only 
variables  and  entire  arrays  passed  by  descriptor  or  by  reference  are 
modifiable. 

5.  An  argument  is  nonmodifiable  when  changes  to  it  are  not  evident 
in  the  calling  program.  Changing  a  nonmodifiable  argument  in  a 
subprogram  does  not  affect  the  value  of  that  argument  in  the  calling 
program.  Arguments  passed  by  value,  constants,  and  expressions  are 
nonmodifiable.  Passing  an  argument  as  an  expression  (by  placing 

it  in  parentheses)  changes  it  from  a  modifiable  to  a  nonmodifiable 
argument.  Virtual  array  elements  passed  as  parameters  are 
nonmodifiable. 

6.  BASlC-PLUS-2  automatically  converts  numeric  actual  parameters  to 
match  the  data  type  declared  by  the  EXTERNAL  statement  for  the 
routine  being  called.  If  the  actual  parameter  is  a  variable, 
BASIC-PLUS-2  signals  the  informational  message  "Mode  for  param¬ 
eter  <n>  of  routine  <name>  changed  to  match  declaration"  and 
passes  the  argument  by  local  copy.  This  prevents  the  called  routine 
from  modifying  the  contents  of  the  variable. 

7.  For  expressions  and  virtual  array  elements  passed  by  reference, 
BASIC-PLUS-2  makes  a  local  copy  of  the  value,  and  passes  the  ad¬ 
dress  of  this  local  copy.  For  dynamic  string  arrays,  BASIC-PLUS-2 
passes  a  descriptor  of  the  array  of  string  descriptors.  The  compiler 
passes  the  address  of  the  argument's  actual  value  for  all  other  argu¬ 
ments  passed  by  reference. 

8.  If  you  attempt  to  call  an  external  function,  BASIC-PLUS-2  treats 
the  function  as  if  it  were  invoked  normally  and  validates  all  param¬ 
eters.  Note  that  you  cannot  call  a  STRING  or  RFA  function.  See 
the  EXTERNAL  statement  for  more  information  on  how  to  invoke 
functions. 

9.  Files  are  not  closed  when  the  CALL  statement  executes. 
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Example 


10  EXTERNAL  SUB  OUTPUT  (string) 

DECLARE  STRING  m8g_str 

i»8g_8tr  «  "Suecsssful  call  to  OUTPUT!" 

CALL  OUTPUT  (m8g_8tr) 

Output 

Successful  call  to  OUTPUT! 
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CAUSE  ERROR 


The  CAUSE  ERROR  statement  allows  you  to  artificially  generate  a 
BASlC-PLUS-2  run-time  error  and  transfer  program  control  to  a 
BASlC-PLUS-2  error  handler. 


Format 

CAUSE  ERROR  err-num 


Syntax  Rules 

Err-num  must  be  a  valid  BASlC-PLUS-2  run-time  error  number. 


Remarks 


See  the  BASlC-PLUS-2  User’s  Guide  for  a  list  of  errors  and  their  corre- 
spending  numbers. 


Example 


10  End.ol.lile.error  *  117. 

CAUSE  ERROR  End_ol_lile_error 


3200  SELECT  ERR 

CASE  *  11 

PRINT  "End  of  file" 
RESUME  32767 
CASE  ELSE 

RESUME  32767 
END  SELECT 


4-14  Statements  and  Functions 


CCPOS 


CCPOS 


The  CCPOS  function  returns  the  current  character  position  or  cursor 
position  of  the  output  record  on  a  specified  channel. 

Format 

int-var  =  CCPOS(chnl-exp} 

Syntax  Rules 

Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number  of  an 
open  file  or  terminal.  You  cannot  precede  the  chnl-exp  with  a  number 
sign  (#). 


Remarks 


1.  If  chnl-exp  is  zero,  CCPOS  returns  the  current  character  position  of  the 
controlling  terminal. 

2.  The  int-var  returned  by  the  CCPOS  function  is  of  the  default  integer 
size. 

3.  The  CCPOS  function  counts  only  characters.  If  you  use  cursor  ad¬ 
dressing  sequences  such  as  escape  sequences,  the  value  returned  will 
not  be  the  cursor  position. 

4.  The  first  character  position  on  a  line  is  zero. 
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Example 


10  DECLARE  LONG  curs.pos 
PRINT  "Hello"; 
curs.pos  »  CCPOS  (0) 
PRINT  curs.pos 

Output 

Hello  5 
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CHAIN 


The  CHAIN  statement  transfers  control  from  the  current  program  to 
another  executable  image.  CHAIN  closes  all  files,  then  requests  that  the 
new  program  begin  execution.  Control  does  not  return  to  the  original 
program  when  the  new  image  finishes  executing. 

NOTE 

The  CHAIN  statement  is  not  recommended  for  new  program 
development.  It  is  recommended  that  you  use  subprograms  and 
external  functions  for  program  segmentation. 


Format 

BASIC-PLUS-2  on  RSX-IIM-PLUS  Systems 

CHAIN  str-exp 

BASIC-PLUS-2  on  RSTS/E  Systems 

CHAIN  str-exp  [  LINE  lin-num  ] 


Syntax  Rules 


1.  Str-exp  represents  the  file  specification  of  the  program  to  which  control 
is  passed.  It  can  be  a  quoted  or  unquoted  string. 

2.  On  RSTS/E  systems,  lin-num  specifies  a  line  number  in  another 
BASIC-PLUS-2  program.  The  line  number  must  exist  and  be  in  the 
range  from  1  through  32767.  The  program  containing  the  line  number 
must  have  been  compiled  with  the  /CHAIN  qualifier. 
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Remarks 


1.  Str-exp  must  refer  to  an  executable  image  or  BASIC-PLUS-2  signals  an 
error. 

2.  If  you  do  not  specify  a  file  type,  BASIC-PLUS-2  searches  for  a  file 
type  of  TSK. 

3.  You  cannot  chain  to  a  program  on  another  node. 

4.  Execution  starts  at  the  first  line  number  of  the  specified  program. 

5.  On  RSTS/E  systems,  if  you  specify  a  lin-num,  execution  starts  at  the 
specified  line  number. 

6.  On  RSTS/E  systems,  if  you  specify  a  line  number  and  the  line  number 
does  not  exist,  BASIC-PLUS-2  signals  an  error. 

7.  Before  chaining  takes  place,  all  active  output  buffers  are  written,  all 
open  files  are  closed,  and  all  storage  is  released.  On  RSTS/E  systems, 
the  last  buffer  (512  bytes)  of  a  terminal-format  file  does  not  get  written 
unless  the  file  is  closed  before  the  CHAIN  statement  executes. 

8.  Because  a  CHAIN  statement  passes  control  from  the  executing  image, 
the  values  of  any  program  variables  are  lost.  This  means  that  you 
can  pass  parameters  to  a  chained  program  only  by  using  files  or  a 
system-specific  feature  such  as  GET/PUT  Core  Common  on  RSTS/E 
systems. 

9.  See  the  BASIC-PLUS-2  User's  Guide  for  information  about  how  the 
CHAIN  statement  is  implemented  on  your  system. 


Example 


Example  1 

10  CHAIN  PR0G2 


100  CHAIN  "PROG6.COM" 

Example  2 

190  ! BASIC-PLUS- 2  on  RSTS/E  systems  only 
200  CHAIN  "NUMBER. TSK"  LINE  390 
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The  CHANGE  statement  either  converts  a  string  of  characters  to  an  array 
of  their  ASCII  integer  values  or  converts  an  array  of  numbers  to  a  string 
of  ASCII  characters. 


Format 

String  Variable  to  Array 

CHANGE  str-exp  TO  num-array-name 

Array  to  String  Variable 

CHANGE  num-array-name  TO  str-var 

Syntax  Rules 

1.  Str-exp  is  a  string  expression. 

2.  Num-array-name  should  be  a  one-dimensional  array.  If  you  specify 
a  two-dimensional  array,  BASIC-PLUS-2  converts  only  the  first  row 
of  that  array.  BASIC-PLUS-2  does  not  support  conversion  to  or  from 
arrays  of  more  than  two  dimensions. 

Remarks 


1.  String  Variable  to  Array 

•  This  format  converts  each  character  in  the  string  to  its  ASCII 
value. 

•  BASIC-PLUS-2  assigns  the  value  of  the  string's  length  to  the  first 
element  of  the  array. 
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•  BASIC-PLUS-2  assigns  the  ASCII  value  of  the  first  character  in  the 
string  to  the  second  element,  ( 1 )  or  (0,1),  of  the  array,  the  ASCII 
value  of  the  second  character  to  the  third  element,  ( 2 )  or  (0,2), 
and  so  on. 

•  If  the  string  is  longer  than  the  bounds  of  the  array, 

BASIC-PLUS-2  does  not  translate  the  excess  characters  and  signals 
the  error  "Subscript  out  of  range"  (ERR=55).  The  first  element  of 
the  array  still  contains  the  length  of  the  string. 

2.  Array  to  String  Variable 

•  This  format  converts  the  elements  of  the  array  to  a  string  of 
characters. 

•  The  length  of  the  string  is  determined  by  the  value  in  the  zero 
element,  (0)  or  (0,0),  of  the  array.  If  the  value  of  element  zero 
is  greater  than  the  array  bounds,  BASIC-PLUS-2  signals  the  error 
"Subscript  out  of  range"  (ERR=55). 

•  BASIC-PLUS-2  changes  the  first  element,  ( 1 )  or  (0,1),  of  the  array 
to  its  ASCII  character  equivalent,  the  second  element,  ( 2 )  or  (0,2), 
to  its  ASCII  equivalent,  and  so  on.  The  length  of  the  returned 
string  is  determined  by  the  value  in  the  zero  element  of  the  array. 
For  example,  if  the  array  is  dimensioned  as  ( 10),  but  the  zero 
element  ( 0 )  contains  the  value  5,  BASIC-PLUS-2  changes  only 
elements  ( 1 ),  ( 2 ),  ( 3 ),  ( 4 ),  and  ( 5 )  to  string  characters. 

•  BASIC-PLUS-2  truncates  floating-point  values  to  integers  before 
converting  them  to  characters. 

•  Values  in  array  elements  are  treated  modulo  256. 
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Example 


10  DECLARE  STRING  ABCD.  A 

DIM  INTEGER  array.changesCO) 
ABCD  *  "ABCD" 

CHANGE  ABCD  TO  array.changes 

FOR  1%  -  0  TO  4 

PRINT  array.changes (1%) 

NEXT  n 

CHANGE  array.changes  TO  A 
PRINT  A 

Output 

4 

65 

66 

67 

68 

ABCD 
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CHR$ 


The  CHR$  function  returns  a  1 -character  string  that  corresponds  to  the 
ASCII  value  you  specify. 


Format 

str-var  =  CHf{$(int-exp) 


Syntax  Rules 

None. 


Remarks 


1.  CHR$  returns  the  character  whose  ASCII  value  equals  int-exp.  If 
int-exp  is  greater  than  255,  BASIC-PLUS-2  treats  it  modulo  256.  For 
example,  CHR$(325)  is  the  same  as  CHR$(69). 

2.  All  arguments  between  0  and  255  are  considered  unsigned  8-bit 
integers.  For  example,  -1  is  treated  as  255. 

3.  If  you  specify  a  floating-point  expression  for  int~exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 


Example 


10  DECLARE  INTEGER  num.exp 

INPUT  "Enter  the  ASCII  value  you  wish  to  be  converted" ;num.exp 
PRINT  "The  equivalent  character  is  " ;CHR$(num_exp) 

Output 

Enter  the  ASCII  value  you  wish  to  be  converted?  89 
The  equivalent  character  is  Y 
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CLOSE 

The  CLOSE  statement  ends  I/O  processing  to  a  device  or  file  on  the 
specified  channel. 


Format 

CLOSE  [#]chnl-exp,  . . . 


Syntax  Rules 

Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  can  be  preceded  by  an  optional  number 
sign  (#). 


Remarks 


1.  BASIC-PLUS-2  writes  the  contents  of  any  active  output  buffers  to  the 
file  or  device  before  it  closes  that  file  or  device. 

2.  Channel  #0  (the  controlling  terminal)  cannot  be  closed.  An  attempt  to 
do  so  has  no  effect. 

3.  If  you  close  a  magnetic  tape  file  that  is  open  for  output, 
BASIC-PLUS-2  writes  an  end-of-file  on  the  magnetic  tape  at  the 
current  tape  position. 

4.  If  you  try  to  close  a  channel  that  is  not  currently  open,  BASIC-PLUS-2 
does  not  signal  an  error  and  the  CLOSE  statement  has  no  effect. 
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Example 


10  OPEN  "COURSE.DAT"  FOR  INPUT  AS  #2 

INPUT  #2,  course.nam,  course.num,  course.desc,  course.lnstr 


CLOSE  «2 
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COMMON 


The  COMMON  statement  defines  a  named,  shared  storage  area  called 
a  COMMON  block  or  program  section  (PSECT).  BASIC-PLUS-2  pro¬ 
gram  modules  can  access  the  values  stored  in  the  COMMON  block  by 
specifying  a  COMMON  block  with  the  same  name. 


Format 


r  COMMON 
I  COM 


[  ( com-name )  ]  {[data-type  ]  corn-item),  . . . 


corn-item: 


'  num-unsubs-var 
num-array-name  ( int-const,  . . .  ) 
str-unsubs-var  =  int-const 

<  str-array-name  ( int-const,  ...}[= int-const  ]  > 
FILL  [  ( int-const }  ][=  int-const  ] 

FILL%  [  { int-const )  ] 

.  FILLS  [  ( int-const )  ][  =  int-const  ] 


Syntax  Rules 


1.  A  COMMON  block  can  have  the  same  name  as  that  of  a  program 
variable,  but  cannot  have  the  same  name  as  that  of  a  subprogram 
within  the  same  task  image. 

2.  A  COMMON  block  and  a  map  in  the  same  program  module  cannot 
have  the  same  name. 

3.  All  COMMON  elements  must  be  separated  with  commas. 

4.  Com-name  names  the  COMMON.  Com-name  is  optional.  If  you  specify 
a  common  name,  it  must  be  in  parentheses.  If  you  do  not  specify  a 
common  name,  the  default  is 
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5.  Corn-name  can  be  from  one  through  six  characters.  The  first  character 
of  the  name  must  be  an  alphabetic  character  (A  through  Z).  The 
remaining  characters,  if  present,  can  be  any  combination  of  letters, 
digits  (0  through  9),  dollar  signs  ($ ),  or  periods  ( . ). 

6.  Data-type  can  be  any  BASlC-PLUS-2  data  type  keyword.  Data  type 
keywords,  size,  range,  and  precision  are  listed  in  Table  1-2  in  this 
manual. 

7.  When  you  specify  a  data  type,  all  following  corn-items,  including  FILL 
items,  are  of  that  data  type  until  you  specify  a  new  data  type. 

8.  If  you  do  not  specify  any  data  type,  corn-items  take  the  current  default 
data  type  and  size. 

9.  Corn-item  declares  the  name  and  format  of  the  data  to  be  stored. 

•  Num-unsubs-var  and  num-array-name  specify  a  numeric  variable  or 
a  numeric  array. 

•  Str-unsubs-var  and  str-array-name  specify  a  fixed-length  string 
variable  or  array.  You  can  specify  the  number  of  bytes  to  be 
reserved  for  the  variable  with  the  =int-const  clause.  The  default 
string  length  is  16. 

•  The  FILL,  FILL%,  and  FILLS  keywords  allow  you  to  reserve  parts 
of  the  record  buffer  within  or  between  data  elements  and  to 
define  the  format  of  the  storage.  Int-const  specifies  the  number 
of  FILL  items  to  be  reserved.  The  =int-const  clause  allows  you  to 
specify  the  number  of  bytes  to  be  reserved  for  string  FILL  items. 
Table  4-2  describes  FILL  item  format  and  storage  allocation. 

NOTE 

In  the  applicable  formats  of  FILL,  (int-const)  represents  a 
repeat  count,  not  an  array  subscript.  FILL  (n)  represents 
n  elements,  not  «  +  1. 
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Table  4-2;  FILL  Item  Formats  and  Storage  Allocations 


FILL  Format 

Storage  Allocation 

FILL 

Allocates  storage  for  one  element  of 
the  default  data  type  unless  preceded 
by  a  data-type;  the  number  of  bytes 
allocated  depends  on  the  default  or 
the  specified  data  type. 

FILL(int-const) 

Allocates  storage  for  the  number  of 
floating-point  elements  specified  by 
int-const  unless  preceded  by  a  data 
type;  the  number  of  bytes  allocated 
for  each  element  depends  on  the 
default  floating-point  data  size  or  the 
specified  data  type. 

FILL% 

Allocates  storage  for  one  integer  ele¬ 
ment;  the  number  of  bytes  allocated 
depends  on  the  default  integer  size. 

FILL%(int-const) 

Allocates  storage  for  the  number  of 
integer  elements  specified  by  int- 
const;  the  number  of  bytes  allocated 
for  each  element  depends  on  the 
default  integer  size. 

FILLS 

Allocates  16  bytes  of  storage  for  a 
string  element.  The  dollar  sign  can 
be  omitted  if  the  FILL  keyword  is 
preceded  by  the  STRING  data  type. 

FILL$(int-const) 

Allocates  16  bytes  of  storage  for  the 
number  of  string  elements  specified 
by  int-const.  The  dollar  sign  can 
be  omitted  if  the  FILL  keyword  is 
preceded  by  the  STRING  data  type. 
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Table  4-2  (Cent.):  FILL  Item  Formats  and  Storage  Allocations 


FILL  Format 

Storage  Allocation 

FILL$=int-const 

Allocates  the  number  of  bytes  of 
storage  specified  by  int<onst  for  a 
string  element.  The  dollar  sign  can 
be  omitted  if  the  FILL  keyword  is 
preceded  by  the  STRING  data  type. 

FILL$(int-constl)=int-const2 

Allocates  the  number  of  bytes  of 
storage  specified  by  int-constl  for  the 
number  of  string  elements  specified 
by  int-constl.  The  dollar  sign  can 
be  omitted  if  the  FILL  keyword  is 
preceded  by  the  STRING  data  type. 

Remarks 


1.  You  should  know  how  your  program  overlays  memory  if  the  data 
stored  in  a  COMMON  area  is  to  be  shared  by  several  program  mod¬ 
ules.  The  COMMON  should  be  named  in  an  overlay  unit  that  will 
remain  in  memory  as  long  as  program  units  need  to  reference  the 
COMMON  data.  If  the  overlay  that  names  the  COMMON  is  forced 
out  of  memory,  BASIC-PLUS-2  reinitializes  the  COMMON  area 

to  zero  when  the  overlay  is  brought  back  into  memory.  See  the 
BASlC-PLUS-2  User's  Guide  for  information  on  overlay  structures. 

2.  A  COMMON  area  and  a  MAP  area  with  the  same  name,  in  different 
program  modules,  specify  the  same  storage  area. 

3.  BASIC-PLUS-2  does  not  execute  COMMON  statements.  The 
COMMON  statement  allocates  and  defines  the  data  storage  area 
at  compilation  time. 

4.  When  you  link  your  program,  the  size  of  the  COMMON  area  is  the 
size  of  the  largest  COMMON  area  with  that  name.  BASIC-PLUS-2 
concatenates  COMMON  statements  with  the  same  corn-name  within  a 
single  program  module  into  a  single  PSECT.  The  total  space  allocated 
is  the  sum  of  the  space  allocated  in  the  concatenated  COMMON 
statements. 
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If  you  specify  the  same  corn-name  in  several  program  modules,  the 
size  of  the  PSECT  will  be  determined  by  the  program  module  that  has 
the  greatest  amount  of  space  allocated  in  the  concatenated  COMMON 
statements. 

5.  The  COMMON  statement  must  lexically  precede  any  reference  to 
variables  declared  in  it. 

6.  A  COMMON  area  can  be  accessed  by  more  than  one  program  module 

com-M«OTe  in  each  module  that  references  the 

COMMON  area. 

7.  Variable  names  in  a  COMMON  statement  in  one  program  module 
need  not  match  those  in  another  program  module. 

8.  Variables  and  arrays  declared  in  a  COMMON  statement  cannot  be  de¬ 
clared  elsewhere  m  the  program  by  any  other  declarative  statements. 

9.  The  data  type  specified  for  corn-items  or  the  default  data  type  and  size 
determines  the  amount  of  storage  reserved  in  a  COMMON  block: 

•  BYTE  integers  reserve  1  byte. 

•  WORD  integers  reserve  2  bytes. 

•  LONG  integers  reserve  4  bytes. 

•  SINGLE  floating-point  numbers  reserve  4  bytes. 

•  DOUBLE  floating-point  numbers  reserve  8  bytes. 

•  STRING  reserves  16  bytes  (the  default)  or  the  number  of  bytes 
you  specify  with  Hnt-const, 

10.  For  multi-dimensional  arrays,  values  are  assigned  in  row-column 
order. 


Example 


10  COMMON  (sales)  INTEGER  shelf .number ,  ft 

STRING  row  -  2,  ft 

report.name  «  24  t 

DOUBLE  FILL,  ^ 

LONG  part.bine 
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C0MP% 

The  COMP%  function  compares  two  numeric  strings  and  returns  a  1,  0, 
or  1,  depending  on  the  results  of  the  comparison. 

Format 

int-var  =  C(iWP%(str-exp1,  str-exp2} 

Syntax  Rules 

Str-expl  and  str-exp2  are  numeric  strings.  They  can  contain  up  to  60  ASCII 
digits,  an  optional  minus  sign  (-),  and  an  optional  decimal  point  ( .). 

Remarks 

1.  If  str-expl  is  greater  than  str-exp2,  COMP%  returns  a  1. 

2.  If  the  string  expressions  are  equal,  COMP%  returns  a  0. 

3.  If  str-expl  is  less  than  str-exp2,  COMP%  returns  a  -1. 

4.  The  value  returned  by  the  COMP%  function  is  an  integer  of  the 
default  size. 

Example 

10  DECLARE  STRING  num.string,  old.num.string ,  k 
INTEGER  result 

num. string  *  "-24.5" 

old. num.string  *  "33" 

result  «  C0MP% (num.string,  old.num.string) 
PRINT  "The  value  is  "; result 

Output 

The  value  is  -1 
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The  COS  function  returns  the  cosine  of  an  angle  in  radians. 

Format 

real-var  =  fiXS%{real-exp} 

Syntax  Rules  ~ 

None. 


Remarks 


1.  The  returned  value  is  between  -1  and  1.  This  value  is  expressed  in 
radians. 

2.  BASIC-PLUS-2  expects  the  argument  of  the  COS  function  to  be  a  real 
expression.  When  the  argument  is  a  real  expression,  BASIC-PLUS-2 
returns  a  value  of  the  same  floating-point  size.  When  the  argument 
is  not  a  real  expression,  BASIC-PLUS-2  converts  the  argument  to 
the  default  floating-point  size  and  returns  a  value  of  the  default 
floating-point  size. 


Example 


10  DECLARE  SINGLE  coe.value 
cos.value  «  26 
PRINT  COS (cos.value) 

Output 

.646919 
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CTRLC 


The  CTRLC  function  enables  CTRL/C  trapping.  When  CTRL/C  trap¬ 
ping  is  enabled,  a  CTRL/C  typed  at  the  terminal  causes  control  to  be 
transferred  to  the  error  handler  currently  in  effect. 


Format 

int-var  =  CTRLC 

Syntax  Rules 

None. 


Remarks 


1.  When  BASlC-PLUS-2  encounters  a  CTRL/C,  control  passes  to  the 
error  handler  currently  in  effect.  If  there  is  no  error  handler  in  a 
program,  the  program  aborts. 

2.  CTRL/C  trapping  is  asynchronous;  that  is,  BASIC-PLUS-2  suspends 
execution  and  signals  the  error  "Programmable  ‘C  trap"  (ERR=28), 
as  soon  as  it  detects  a  CTRL/C.  Consequently,  a  statement  can  be 
interrupted  while  it  is  executing.  A  statement  so  interrupted  may  be 
only  partially  completed  and  variables  may  be  left  in  an  undefined 
state. 

3.  BASIC-PLUS-2  can  trap  more  than  one  CTRL/C  error  in  a  program  as 
long  as  the  error  does  not  occur  while  the  error  handler  is  executing. 

If  a  second  CTRL/C  is  detected  while  the  error  handler  is  processing 
the  first  CTRL/C,  the  program  aborts. 

4.  On  RSX  systems,  the  task  that  contains  the  CTRLC  functioii  must  be 
able  to  attach  to  a  terminal  as  soon  as  the  CTRLC  fucntion  is  enabled. 
If  another  task  is  attached  to  the  terminal,  the  task  that  enabled  the 
CTRLC  function  terminates  with  a  directive  error. 

5.  The  CTRLC  function  always  returns  a  value  of  zero. 
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Example 


10  ON  ERROR  GOTO  19000 
n  -  CTRLC 


IF  (ERR-28) 

RESUME  Ctrlc.handler 
END  IF 
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CVT$$ 


The  CVT$$  function  is  a  synonym  for  the  EDITS  function.  See  the  EDITS 
function  for  more  information. 


NOTE 

The  CVTSS  function  is  supported  only  for  compatibility  with 
BASIC-PLUS.  It  is  recommended  that  you  use  the  EDITS 
function  for  new  program  development. 


Format 

str-var  =  C\n$$(str-exp,  int-expj 
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CVTxx 


The  CVT$%  function  maps  the  first  two  characters  of  a  string  into  a  16-bit 
integer.  The  CVT%$  function  translates  a  16-bit  integer  into  a 
2-character  string.  The  CVT$F  function  maps  a  4-  or  8-character  string 
into  a  floating-point  variable.  The  CVTF$  function  translates  a  floating¬ 
point  number  into  a  4-  or  8-byte  character  string.  The  number  of  charac¬ 
ters  translated  depends  on  whether  the  floating-point  variable  is  single-  or 
double-precision. 

NOTE 

The  CVTxx  function  is  supported  only  for  compatibility  with 
BASIC-PLUS.  It  is  recommended  that  you  use  BASIC-PLUS-2 
dynamic  mapping  or  multiple  MAP  statements  for  new  program 
development. 


Format 

int-var  =  Cyj$%(str-var} 
real-var  =  C}n$f(str-var} 
str-var  =  C\n%$  (int-var) 
str-var  =  C\Hf$  (real-var) 


Syntax  Rules 

None. 
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Remarks 


1.  CVT$% 

•  If  the  CVT$%  str-var  has  fewer  than  two  characters, 
BASIC-PLUS-2  pads  the  string  with  nulls. 

•  The  value  returned  by  the  CVT$%  function  is  an  integer  of  the 
default  size. 

2.  CVT«/o$ 

•  Only  two  bytes  of  data  are  inserted  into  str-var. 

•  If  you  specify  a  floating-point  variable  for  int-var,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size.  If  the  default  size  is 
BYTE  and  the  value  of  int-var  exceeds  127,  BASIC-PLUS-2  signals 
an  error. 

3.  CVT$F 

•  CVT$F  maps  four  characters  when  the  program  is  compiled  with 
/SINGLE  and  eight  characters  when  the  program  is  compiled  with 
/DOUBLE. 

•  If  str-var  has  fewer  than  four  or  eight  characters,  BASIC-PLUS-2 
pads  the  string  with  nulls. 

•  The  real-var  returned  by  the  CVT$F  function  is  the  default 
floating-point  size. 

4.  CVTF$ 

•  The  CVTF$  function  maps  single-precision  numbers  to  a 
4-character  string  and  double-precision  numbers  to  an  8-character 
string. 

•  BASIC-PLUS-2  expects  the  argument  of  the  CVTF$  fuiiction  to  be 
a  real  expression.  When  the  argument  is  a  real  expression, 
BASIC-PLUS-2  returns  a  value  of  the  same  floating-point  size. 
When  the  argument  is  not  a  real  expression,  BASIC-PLUS-2 
converts  the  argument  to  the  default  floating-point  size  and 
returns  a  value  of  the  default  floating-point  size. 
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Examples 


Example  1 

10  DECLARE  STRING  test.s'trlng,  another  atrlng 
DECLARE  WORD  first .number,  next .number 
test.strlng  *  "AT" 

PRINT  CVTIX (test.strlng) 
another.string  *  "at" 

PRINT  CVT$%( another.string) 
fir St. number  *  16724 
PRINT  cmidirst.nurnber) 
next.number  »  24948 
PRINT  cm$  (next.number) 

END 

Output  1 

16724 

24948 

AT 

at 

Example  2 

10  DECLARE  STRING  test.strlng,  another.string 
DECLARE  SINGLE  flrst.num,  second.num 
test.strlng  *  "DESK" 
flrst.num  »  CVT$F (test.strlng) 

PRINT  flrst.num 
another.string  »  "desk" 
second.num  *  CVT$F (another.string) 

PRINT  second.num 
PRINT  CVTFI (flrst.num) 

PRINT  CVTFI (second.num) 

END 

Output  2 

.218256E-i'12 

.466242E-*'31 

DESK 

desk 
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The  DATA  statement  creates  a  data  block  for  the  READ  statement. 


Format 


DATA 


■  num-lit  ■ 
str-lit  ,  ■  ■  ■ 
.  unq-str  . 


Syntax  Rules 


1.  Num-lit  specifies  a  numeric  literal. 

2.  Str-lit  is  a  character  string  that  starts  and  ends  with  double  or  single 
quotation  marks.  The  quotation  marks  must  match. 

3.  Unq-str  is  a  character  sequence  that  does  not  start  or  end  with  double 
quotation  marks  and  does  not  contain  a  comma. 

4.  Commas  separate  data  elements.  If  a  comma  is  part  of  a  data  item, 
the  entire  item  must  be  enclosed  in  quotation  marks. 


Remarks 


1.  Because  BASIC-PLUS-2  treats  comment  fields  in  DATA  statements  as 
part  of  the  DATA  sequence,  you  should  not  include  comments. 

2.  A  DATA  statement  must  be  the  last  or  the  only  statement  on  a 
physical  line. 

3.  DATA  statements  must  end  with  a  line  terminator. 

4.  When  a  DATA  statement  is  continued  with  an  ampersand  (&), 
BASIC-PLUS-2  interprets  all  characters  between  the  keyword  DATA 
and  the  ampersand  as  part  of  the  data.  Any  code  that  appears  on  a  ^ 
noncontinued  line  is  considered  a  new  statement. 
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5.  You  cannot  use  the  percent  sign  suffix  for  integer  constants  that  appear 
in  DATA  statements.  An  attempt  to  do  so  causes  BASIC-PLUS-2  to 
signal  the  error  "Data  format  error"  (ERR=50). 

6.  DATA  statements  are  local  to  a  program  module. 

7.  BASIC-PLUS-2  does  not  execute  DATA  statements.  Instead,  control  is 
passed  to  the  next  executable  statement. 

8.  A  program  can  have  more  than  one  DATA  statement.  BASIC-PLUS-2 
assembles  data  from  all  DATA  statements  in  a  single  program  unit  into 
a  lexically  ordered  single  data  block. 

9.  BASIC-PLUS-2  ignores  leading  and  trailing  blanks  and  tabs  unless 
they  are  in  a  string  literal. 

10.  Commas  are  the  only  valid  data  delimiters.  You  must  use  a  quoted 
string  literal  if  a  comma  is  to  be  part  of  a  string. 

11.  BASIC-PLUS-2  ignores  DATA  statements  without  an  accompanying 
READ  statement. 

12.  BASIC-PLUS-2  signals  the  error  "Data  format  error"  (ERR=50)  if  the 
DATA  item  does  not  match  the  data  type  of  the  variable  specified  in 
the  READ  statement  or  if  a  data  element  that  is  to  be  read  into  an 
integer  variable  ends  with  a  percent  sign  ( % ).  If  a  string  data  element 
ends  with  a  dollar  sign  ($),  BASIC-PLUS-2  treats  the  dollar  sign  as 
part  of  the  string. 


10  DECURE  INTEGER  A,B,C 
READ  A.B.C 
DATA  1,2,3 
PRINT  A  ♦  B  +  C 

Output 
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DATES 

The  DATES  function  returns  a  string  containing  a  day,  month,  and  year  in 
the  form  dd-Mmm-yy. 


Format 

str-var  =  UMltlint-exp) 


Syntax  Rules 

1.  Int-exp  can  have  up  to  six  digits  in  the  form  yyyddd,  where  the  charac¬ 
ters  yyy  specify  the  number  of  years  since  1970  and  the  characters  ddd 
specify  the  day  of  that  year. 

2.  You  must  fill  all  three  of  the  d  positions  with  digits  or  zeros  before 
you  can  fill  the  y  positions.  For  example: 

•  DATE$(121)  returns  the  date  Ol-May-70,  day  121  of  the  year 

1970. 

•  DATE$(1201)  returns  the  date  20-Jul-71,  day  201  of  the  year 

1971. 

•  DATE$(12001)  returns  the  date  Ol-Jan-82,  day  one  of  the  year 
1982. 

•  DATE$(10202)  returns  the  date  21-Jul-80,  day  202  of  the  year 
1980. 
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Remarks 


1.  If  int-exp  equals  zero,  DATES  returns  the  current  date. 

2.  The  str-var  returned  by  the  DATES  function  consists  of  nine  characters 
and  expresses  the  day,  month,  and  year  in  the  form  dd-Mmm-yy. 

4.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 

5.  On  RSTS/E  systems,  the  form  of  the  DATES  function's  output  can  be 
changed  to  ISO  format,  yy.mm.dd,  during  the  installation  procedure, 
or  to  the  format  selected  by  the  system  manager  at  system  start-up 


Example 


10  DECLARE  STRING  todays.date 
todays.date  »  DATE$(0) 
PRINT  todaya.date 


Output 

26-Aug-86 
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The  DECLARE  statement  explicitly  assigns  a  name  and  a  data  type  to  a 
variable,  an  entire  array,  a  function,  or  a  constant. 


Format 

Variables 

DECLARE  data-type  decl-item  [,[  data-type  ]  dad-item  ],  . . . 


DEF  Functions 

DECLARE  data-type  FUNCTIDN  {  def-name  [  ( [  def-param  ],  . 

Named  Constants 

DECLARE  data-type  CDNSTANT  {  const-name  =  const-exp  ),  . 
....  f  array-name  ( int-const,  . . ,  ^  1 

l  mL-m  } 

def-param:  [  data-type  ] 


.}]}, 


Syntax  Rules 

1.  Data-type  can  be  any  BASIC-PLUS-2  data  type  keyword.  Data  type 
keywords,  size,  range,  and  precision  are  listed  in  Table  1-2  m  this 
manual. 

2.  Variables 

•  Decl-item  names  an  array  or  a  variable. 

•  A  decl-item  named  in  a  DECLARE  statement  cannot  be  named 
in  another  DECLARE  statement,  or  in  a  DEF,  EXTERNAL, 
FUNCTION,  SUB,  COMMON,  MAP,  or  DIM  statement. 

•  Inst-const  specifies  the  upper  bounds  of  the  array. 

•  Each  decl-item  is  associated  with  the  preceding  data  type,  A  data 

''  tyP®  i®  required  for  the  first  decl-item. 
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•  Decl-itetns  of  data  type  STRING  are  dynamic  strings. 

3.  DEF  Functions 

•  Def-name  names  the  DEF  function. 

•  Data-type  specifies  the  data  type  of  the  value  the  function  returns. 

•  Data  type  keywords  must  be  separated  by  commas. 

•  Def-params  specify  the  number  and,  optionally,  the  data  type  of 
the  DEF  parameters.  Parameters  define  the  arguments  the  DEF 
expects  to  receive  when  invoked. 

When  you  specify  a  data  type,  all  following  parameters  are  of 
that  data  type  until  you  specify  a  new  data  type. 

—  If  you  do  not  specify  any  data  type,  parameters  take  the 
current  default  data  type  and  size. 

The  number  of  parameters  equals  the  number  of  commas  plus 
(me.  For  example,  empty  parentheses  specify  one  parameter  of 
the  (default  type  and  size,  one  comma  inside  the  parentheses 
specifies  two  parameters  of  the  default  type  and  size,  and 
so  on.  One  data  type  inside  the  parentheses  specifies  one 
parameter  of  the  specified  data  type;  two  data  tj^es  separated 
by  one  comma  specifies  two  parameters  of  the  specified  type 
and  so  on.  ^ 

4.  Named  Constants 

•  Const-nutne  is  the  name  you  assign  to  the  constant. 

•  Data-type  specifies  the  data  type  of  the  constant.  The  value  of  the 
const  must  be  numeric  if  the  data  type  is  numeric  and  string  if  the 
data  type  is  STRING.  If  the  data  type  is  STRING,  const  must  be  a 
quoted  string  or  another  string  constant. 

•  Const-exp  cannot  be  of  the  RFA  data  type. 

•  String  constants  cannot  exceed  128  characters. 

•  BASIC-PLUS-2  allows  const-exp  to  be  an  expression  for  STRING 
and  INTEGER  data  types.  Expressions  are  not  allowed  as  values 
when  you  name  floating-point  constants. 

•  Allowable  operators  in  DECLARE  CONSTANT  expressions  in- 
elude  all  valid  arithmetic,  relational,  and  logical  operators  except 
exponentiation.  Built-in  functions  cannot  be  used  in  DECLARE 
CONSTANT  expressions.  The  following  example  uses  valid 
expressions  as  values: 

DECLARE  STRING  CONSTANT  left_arrow  *  ^  Lp  ^  /jn 
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Remarks 


1.  The  DECLARE  statement  is  not  executable. 

2.  The  DECLARE  statement  must  lexically  precede  any  reference  to  the 

variables,  functions,  or  constants  named  in  it. 

3.  To  declare  a  virtual  or  run-time  array,  use  the  DIMENSION  statement. 

4.  Variables 

•  Subsequent  decl-items  are  associated  with  the  specified  data  type 
until  you  specify  another  data  type. 

•  All  variables  named  in  a  DECLARE  statement  are  initialized  to 
zero  if  numeric  or  to  the  null  string  if  string. 

5.  DEE  Functions 

•  The  DECLARE  FUNCTION  statement  allows  you  to  name  a 
function  defined  in  a  DEF  or  DEF*  statement,  specify  the  data  type 
of  the  value  the  function  returns,  and  declare  the  number  and  data 
type  of  the  DEF  parameters. 

•  The  first  specification  of  a  data  type  for  a  def-param  is  the  default 
for  subsequent  arguments  until  you  specify  another  def-param. 

•  Data-type  keywords  must  be  separated  by  commas.  For  example. 


10  DECLARE  DOUBLE  FUNCTION  interest (DOUBLE, SINGLE. ,) 

This  example  declares  two  parameters  of  the  default  type  and  size, 
one  DOUBLE  parameter,  and  three  SINGLE  parameters  for  the 
function  named  interest. 

6.  Named  Constants 

•  The  DECLARE  CONSTANT  statement  allows  you  to  name  a 
constant  value  and  assign  a  data  type  to  that  value.  Note  that 
you  can  specify  only  one  data  type  in  a  DECLARE  CONSTAN 1 
statement.  To  declare  a  constant  of  another  data  type,  you  must 
use  a  second  DECLARE  CONSTANT  statement. 

•  During  program  execution,  you  cannot  change  the  value  assigned 
to  the  constant. 
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•  You  cannot  use  a  const-nam  where  a  variable  is  required. 

•  BASIC-PLUS-2  signals  an  error  if  the  data  type  of  const-exp  does 
not  match  the  specified  data  type. 

NOTE 

Data  types  specified  in  a  DECLARE  statement  override 
any  defaults  specified  in  COMPILE  command  qualifiers  or 
OPTION  statements. 

7.  Although  the  data  types  LONG,  WORD,  and  BYTE  allow  the  values 
-21474813648,  -32768,  and  -128,  you  cannot  specify  these  constants 
explicitly.  If  you  specify  these  values  explicitly,  BASIC-PLUS-2  signals 
an  integer  overflow  error.  You  can  create  integer  constants  with  these 
values  only  if  you  supply  their  value  with  an  expression.  For  example: 

DECLARE  WORD  CONSTANT  X  »  -32767  -  1 


Examples 


Example  1 

10  !DEF  functions 

DECLARE  INTEGER  FUNCTION  amount (DOUBLE, BYTE) 

Example  2 

10  ! Named  Constants 

DECLARE  DOUBLE  CONSTANT  interest.rate  »  16.22 
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The  DEF  statement  lets  you  define  a  single-  or  multi-line  function. 


Format 


Single-line  DEF 

DEF  [ data-type ] def-name [ ( [ data-type ] unsubs-var ,  }]=exp 

Multi-Line  DEF 

DEF  [  data-type  ]  def-name  [  ( [  data-type  unsubs-var  ],...)][  statement  ]  . . . 
[  statement  ]... 


[  exp] 


Syntax  Rules 


1.  Data-type  can  be  any  BASlC-PLUS-2  data  type  keyword.  Data  type 
keywords,  size,  range,  and  precision  are  listed  in  Table  1-2  in  this 
manual. 

2.  The  data  type  that  precedes  the  def-name  specifies  the  data  type  of  the 
value  returned  by  the  DEF  function. 

3.  Def-name  is  the  name  of  the  DEF  function.  The  def-name  can  contain 
from  1  through  31  characters. 

4.  If  the  def-name  also  appears  in  a  DECLARE  FUNCTION  statement, 
the  following  rules  apply: 

•  A  function  data  type  is  required. 

•  The  first  character  of  the  def-name  must  be  an  alphabetic  character 
(A  through  Z).  The  remaining  characters  can  be  any  combination 
of  letters,  digits  (0  through  9),  dollar  signs  ($),  underscores  (_), 
or  periods  ( . ). 
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5.  If  the  def-name  does  not  appear  in  a  DECLARE  FUNCTION  statement, 
but  the  DEF  statement  appears  before  the  first  reference  to  the 
def~name,  the  following  rules  apply: 

•  The  function  data  type  is  optional. 

•  The  first  character  of  the  def-name  must  be  an  alphabetic  letter 
(A  through  Z).  The  remaining  characters  can  be  any  combination 
of  letters,  digits,  dollar  signs,  underscores,  or  periods. 

•  If  a  function  data  type  is  not  specified,  the  last  character  in  the 
def-name  must  be  a  percent  sign  for  an  INTEGER  function,  or 
a  dollar  sign  for  a  STRING  function;  otherwise,  it  will  take  the 
current  default  data  type. 

6.  If  the  def-name  does  not  appear  in  a  DECLARE  FUNCTION  statement, 
and  the  DEF  statement  appears  after  the  first  reference  to  the  def-name, 
the  following  rules  apply: 

•  The  function  data  type  cannot  be  present. 

•  The  first  two  characters  of  the  def-name  must  be  FN.  The  remain¬ 
ing  characters  can  be  any  combination  of  letters,  digits,  dollar 
signs,  or  periods,  with  one  restriction:  the  last  character  must  be 
a  percent  sign  for  an  INTEGER  function,  or  a  dollar  sign  for  a 
STRING  function. 

•  There  must  be  at  least  one  character  between  the  FN  characters 
and  the  ending  dollar  sign  or  percent  character.  FN$  and  FN%  are 
not  valid  function  names. 

7.  Unsubs-var  specifies  optional  formal  DEF  parameters.  Because  the 
parameters  are  local  to  the  DEF  function,  any  reference  to  these 
variables  outside  the  DEF  body  creates  a  different  variable. 

8.  You  can  specify  the  data  type  of  DEF  parameters  with  a  data  type 
keyword.  If  you  do  not  include  a  data  type,  the  parameters  are  of  the 
default  type  and  size.  Parameters  that  follow  a  data  type  keyword  are 
of  the  specified  type  and  size  until  you  specify  another  data  type. 

9.  You  can  specify  up  to  32  parameters  in  a  DEF  statement. 

10.  Single-Line  DEF 

Exp  specifies  the  operations  the  function  performs. 

11.  Multi-Line  DEF 

•  Statements  specifies  the  operations  the  function  performs. 

•  The  END  DEF  or  FNEND  statement  is  required  to  end  a  multi-line 
DEF. 
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•  BASIC-PLUS-2  does  not  allow  you  to  specify  any  statements 
that  indicate  the  beginning  or  end  of  any  SUB,  FUNCTION,  or 
PROGRAM  in  a  function  definition. 

•  Exp  specifies  the  function  result.  Exp  must  be  compatible  with  the 
DEF  data  type. 


Remarks 


1.  When  BASIC-PLUS-2  encounters  a  DEF  statement,  control  of  the 
program  passes  to  the  next  executable  statement  after  the  DEF. 

2.  The  function  is  invoked  when  you  use  the  function  name  in  an 
expression. 

3.  You  cannot  specify  how  parameters  are  passed.  When  you  invoke  a 
function,  BASIC-PLUS-2  evaluates  parameters  from  left  to  right  and 
passes  parameters  to  the  function  so  that  they  cannot  be  modified. 
Numeric  parameters  are  passed  by  value  and  string  parameters  are 
passed  by  descriptor,  where  the  descriptor  points  to  a  local  copy. 

DEF  functions  can  reference  variables  in  the  main  program,  but  they 
cannot  reference  variables  in  other  DEF  or  DEF*  functions.  A  DEF 
function  can,  therefore,  modify  other  variables  in  the  program,  but  not 
variables  within  another  DEF  function. 

4.  A  DEF  function  is  local  to  the  program,  subprogram,  or  function  that 
defines  it. 

5.  You  can  declare  a  DEF  by  defining  it,  by  using  the  DECLARE 
FUNCTION  statement,  or  by  implicitly  declaring  it  with  a  reference  to 
the  function  in  an  expression. 

6.  If  your  program  invokes  a  function  with  a  name  that  does  not  start 
with  FN  before  the  DEF  statement  defines  the  function, 

BASIC-PLUS-2  signals  an  error. 

7.  If  the  number  of  parameters,  types  of  parameters,  or  type  of  result 
declared  in  the  invocation  disagree  with  the  number  or  types  of 
parameters  defined  in  the  DEF  statement,  BASIC-PLUS-2  signals  an 
error. 

8.  DATA  statements  in  a  multi-line  DEF  are  not  local  to  the  func¬ 
tion;  they  are  local  to  the  program  module  containing  the  function 
definition. 
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9.  To  return  a  value  in  a  multi-line  DEF,  make  an  assignment  to  the  DEF 
function  name  from  inside  the  DEF  function,  or  supply  a  value  in  an 
EXIT  DEF  or  END  DEF  statement.  You  can  only  assign  a  value  to  a 
DEF  function  name  while  inside  the  DEF  function. 

10.  The  function  value  is  initialized  to  zero  or  the  null  string  each  time 
you  invoke  the  function. 

11.  ON  ERROR  GO  BACK  is  the  default  error  handler  in  a  DEF  function 
definition. 

12.  If  an  error  occurs  in  a  DEF  function  that  is  not  handled  in  the  DEF 
function,  control  passes  to  the  error  handler  of  the  main  program.  If 
the  main  program  has  no  error  handler,  control  passes  to  the  default 
BASIC-PLUS-2  error  handler. 

13.  ON  ERROR  statements  within  a  DEF  function  are  local  to  the  function. 

14.  A  GOTO,  GOSUB,  ON  ERROR  GOTO,  or  RESUME  statement  in  a 
multi-line  function  definition  must  refer  to  a  line  number  or  label  in 
the  same  function  definition. 

15.  You  cannot  transfer  control  into  a  multi-line  DEF  except  by  invoking 
the  function. 

16.  DEF  functions  can  be  recursive;  however,  BASIC-PLUS-2  does  not 
detect  infinitely  recursive  DEF  functions.  If  your  program  invokes 
an  infinitely  recursive  DEF  function,  your  program  will  eventually 
terminate  with  a  fatal  error. 


Examples 


Example  1 

10  ! Single-Line  DEF 

DEF  DOUBLE  add  (DOUBLE  A,  B.  SINGLE  C.  D,  E)-A+B+C+D+E 
INPUT  'Enter  live  numbers  to  be  added' ;V,W,X.Y,Z 
PRINT  'The  sum  is' ;ADD(V,W,X.Y.Z) 

Output  1 

Enter  live  numbers  to  be  added?  1,2, 3, 4. 6 
The  sum  is  15 

Example  2 

10  I  PROGRAM  I_want_a_ralse 
OPTION  SCALE  -  2 
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DECLARE  DOUBLE  CONSTANT  Overtime.lactor  *  0.60 
DECLARE  DOUBLE  My .hours,  My .rate,  Overtime 

DEF  DOUBLE  Calculate.pay  (DOUBLE  Hours,  Rate) 

Overtime  *  Hours  -  40.0 
Overtime  *  0.0  IF  Overtime  <0.0 

Calculate.pay  ■  (Hours  ♦  Rate)  +  (Overtime  *  Overtime.lactor  ♦  Rate) 


END  DEF 

INPUT  'Your  hours  this  week' ; My .hours 
INPUT  'Your  hourly  rate '; My. rate 

PRINT  'My  pay  this  week  is' ; Calculate.pay  (My .hours, My. rate) 
END 


Output  2 

Your  hours  this  week?  45.7 
Your  hourly  rate?  20.36 
My  pay  this  week  is  987.96 
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The  DEF*  statement  lets  you  define  a  single-  or  multi-line  function. 


NOTE 


The  DEF*  statement  is  not  recommended  for  new  program  de¬ 
velopment.  It  is  recommended  that  you  use  the  DEF  statement 
for  defining  single-  and  multi-line  functions. 


Format 


Single-line  DEF* 

DEF*  [ data-type ] def-name [([ data-type ] unsubs-var ,  )]  =  exp 

Multi-Line  DEF* 

DEF*  [  data-type  ]  def-name  [  ( [  data-type  ]  unsubs-var ,...)][  statement  ]  . . . 
[  statement  ]  . . . 


[exp] 


Syntax  Rules 


1.  Data-type  can  be  any  BASIC-PLUS-2  data  type  keyword.  Data  type 
keywords,  size,  range,  and  precision  are  listed  in  Table  1-2  in  this 
manual. 

2.  The  data  type  that  precedes  the  def-name  specifies  the  data  type  of  the 
value  returned  by  the  DEF*  function. 

3.  Def-name  is  the  name  of  the  DEF*  function.  The  def-name  can  contain 
from  1  to  31  characters. 

4.  If  the  def-name  also  appears  in  a  DECLARE  FUNCTION  statement, 
the  following  rules  apply: 

•  A  function  data  type  is  required. 
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•  The  first  character  of  the  def-name  must  be  an  alphabetic  character 
(A  through  Z).  The  remaining  characters  can  be  any  combination 
of  letters,  digits  (0  through  9),  dollar  signs  ($),  underscores  (_), 
or  periods  ( . ). 

5.  If  the  def-name  does  not  appear  in  a  DECLARE  FUNCTION  statement, 
but  the  DEF*  statement  appears  before  the  first  reference  to  the 
def-name,  the  following  rules  apply: 

•  The  function  data  type  is  optional. 

•  The  first  character  of  the  def-name  must  be  an  alphabetic  character 
(A  through  Z).  The  remaining  characters  can  be  any  combination 
of  letters,  digits,  dollar  signs,  underscores,  or  periods. 

•  If  a  function  data  type  is  not  specified,  the  last  character  in  the 
def-name  must  be  a  percent  sign  for  an  INTEGER  function,  or  a 
dollar  sign  for  a  STRING  function,  or  the  function  will  take  the 
default  data  type  and  size. 

6.  If  the  def-name  does  not  appear  in  a  DECLARE  FUNCTION  statement, 
and  the  DEF*  statement  appears  after  the  first  reference  to  the 
def-name,  the  following  rules  apply: 

•  The  function  data  type  cannot  be  present. 

•  The  first  two  characters  of  the  def-name  must  be  FN.  The  remain¬ 
ing  characters  can  be  any  combination  of  letters,  digits,  dollar 
signs,  or  periods,  with  one  restriction:  the  last  character  must  be 
a  percent  sign  for  an  INTEGER  function,  or  a  dollar  sign  for  a 
STRING  function;  otherwise,  the  function  takes  the  default  data 
type  and  size. 

•  There  must  be  at  least  one  character  between  the  FN  characters 
and  the  ending  dollar  sign  or  percent  character.  FN$  and  FN%  are 
not  valid  function  names. 

7.  Unsubs-var  specifies  optional  formal  function  parameters. 

8.  You  can  specify  the  data  type  of  function  parameters  with  a  data  type 
keyword.  If  you  do  not  specify  a  data  type,  parameters  are  of  the 
default  type  and  size.  Parameters  that  follow  a  data  type  are  of  the 
specified  type  and  size  until  you  specify  another  data  type. 

9.  You  can  specify  up  to  32  parameters  in  a  DEF*  statement. 

10.  Single-Line  DEF* 

Exp  specifies  the  operations  the  function  performs. 

11.  Multi-Line  DEF* 

•  Statements  specifies  the  operations  the  function  performs. 
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•  The  END  DEF  or  FNEND  statement  is  required  to  end  a  multi-line 
DEF* *. 

•  BASIC-PLUS-2  does  not  allow  you  to  specify  any  statements  that 
indicate  the  beginning  of  any  SUB,  FUNCTION,  PROGRAM,  or 
DEF,  or  the  end  or  any  SUB,  FUNCTION,  or  PROGRAM,  in  a 
function  definition. 

•  Exp  specifies  the  function  result.  Exp  must  be  compatible  with  the 
DEF  data  type. 


Remarks 


1.  When  BASIC-PLUS-2  encounters  a  DEF*  statement,  control  of  the 
program  passes  to  the  next  executable  statement  after  the  DEF*. 

2.  A  function  defined  by  the  DEF*  statement  is  invoked  when  you  use 
the  function  name  in  an  expression. 

3.  You  cannot  specify  how  parameters  are  passed.  When  you  invoke  a 
DEF*  function,  BASIC-PLUS-2  evaluates  parameters  from  left  to  right 
and  passes  parameters  to  the  function  so  that  they  cannot  be  modified. 
Numeric  parameters  are  passed  by  value,  and  string  parameters  are 
passed  by  descriptor,  where  the  descriptor  points  to  a  local  copy. 
DEF*  functions  can  reference  variables  in  the  main  program,  but  they 
cannot  reference  variables  in  other  DEF  or  DEF*  functions.  A  DEF* 
function  can,  therefore,  modify  variables  in  the  program,  but  not 
variables  within  another  DEF*  function. 

4.  The  following  differences  exist  between  DEF*  and  DEF  statements: 

•  You  can  use  the  GOTO,  ON  GOTO,  GOSUB,  and  ON  GOSUB 
statements  to  a  branch  outside  a  multi-line  DEF*,  but  they  are  not 
recommended. 

•  Although  other  variables  used  within  the  body  of  a  DEF*  function 
are  not  local  to  the  DEF*  function,  DEF*  formal  parameters  are. 

If  you  change  the  value  of  formal  parameters  within  a  DEF* 
function  and  then  transfer  control  out  of  the  DEF*  function 
without  executing  the  END  DEF  or  FNEND  statement,  variables 
outside  the  DEF*  that  have  the  same  names  as  DEF*  formal 
parameters  are  also  changed. 

•  A  DEF*  function  value  is  not  initialized  when  the  DEF*  function 
is  invoked.  Therefore,  if  a  DEF*  function  is  invoked,  and  no  new 
function  value  is  assigned,  the  DEF*  function  returns  the  value  of 
its  previous  invocation. 
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•  The  error  handler  of  the  program  module  that  contains  the  DEF* 
is  the  default  error  handler  for  a  DEF*  function.  Parameters  return 
to  their  original  values  when  control  passes  to  the  error  handler. 

5.  A  DEF*  is  local  to  the  program  or  subprogram  that  defines  it. 

6.  You  can  declare  a  DEF*  either  by  defining  it,  by  using  the  DECLARE 
FUNCTION  statement,  or  by  implicitly  declaring  it  with  a  reference  to 
the  function  in  an  expression. 

7.  If  the  number  of  parameters,  types  of  parameters,  or  type  of  result 
declared  in  the  invocation  disagree  with  the  number  or  types  of 
parameters  defined  in  the  DEF*  statement,  BASIC-PLUS-2  signals  an 
error. 

8.  DEF*  functions  can  be  recursive;  however,  BASIC-PLUS-2  does  not 
detect  infinitely  recursive  DEF*  functions.  If  your  program  invokes 
an  infinitely  recursive  DEF*  function,  your  program  will  eventually 
terminate  with  a  fatal  error. 

9.  DATA  statements  in  a  multi-line  DEF*  are  not  local  to  the  func¬ 
tion;  they  are  local  to  the  program  module  containing  the  function 
definition. 

10.  To  return  a  value  in  a  multi-line  DEF*,  make  an  assignment  to  the 
DEF  function  from  inside  the  DEF  function,  or  assign  a  value  to  an 
EXIT  DEF  or  END  DEF  statement.  You  can  assign  a  value  to  a  DEF 
function  only  while  inside  the  DEF  function. 

11.  You  can  pass  up  to  32  parameters  to  a  DEF*  function. 


r 


4-54  Statements  and  Functions 


DEF« 


Examples 


Example  1 

10  !Slngle-Llne  DEF* 

DEF*  STRING  CONCAT(STRING  A.B)  >  A  +  B 
DECLARE  STRING  wordl,word2 
INPUT  "Enter  two  words” ;wordl,word2 
PRINT  CONCAT  (wordl . word2) 

Output  1 

Enter  two  words?  TO 

?  DAY 

TODAY 

Example  2 

10  ! Multi -Line  DEF* 

DEF*  DOUBLE  example (DOUBLE  A.  B.  SINGLE  C.  D.  E) 
EXIT  DEF  IF  B  «  0 
example  *  (A/B)  +  C  -  (D*E) 

END  DEF 

INPUT  "Enter  6  numbers" ;V.W.X.Y,Z 
PRINT  example (V,W,X,Y,Z) 

Output  2 

Enter  5  numbers?  2, 4, 6. 8,1 
-1.5 
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DELETE 


The  DELETE  statement  removes  a  record  from  a  relative  or  indexed  file. 


Format 

DELETE  #chnl-exp 


Syntax  Rules 

Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 


Remarks 


1.  The  DELETE  statement  removes  the  current  record  from  a  file.  Once 
the  record  is  removed,  you  cannot  access  it. 

2.  The  file  specified  by  chnl-exp  must  have  been  opened  with  ACCESS 
MODIFY  or  WRITE. 

3.  You  can  delete  a  record  only  if  the  last  I/O  statement  executed  on  the 
specified  channel  was  a  successful  GET  or  FIND  operation. 

4.  The  DELETE  statement  leaves  the  current  record  pointer  undefined 
and  the  next  record  pointer  unchanged. 

5.  BASIC-PLUS-2  signals  an  error  when  the  following  conditions  exist: 

•  The  I/O  channel  is  illegal  or  not  open. 

•  No  current  record  exists. 

•  The  specified  record  is  locked. 

•  Record  access  is  illegal  or  illogical. 

•  The  operation  is  illegal. 
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Example 


10  DECLARE  STRING  record.num 


OPEN  "CUS.DAT"  FOR  INPUT  AS  #1.  RELATIVE  FIXED  k 

ACCESS  MODIFY.  RECORDSIZE  40 


INPUT  "WHICH  RECORD  WOULD  YOU  LIKE  TO  EXAMINE" ;record_num 
GET  #1.  RECORD  record.nuffl 
DELETE  #1 
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DET 


The  DET  function  returns  the  value  of  the  determinant  of  the  last  matrix 
inverted  with  the  MAT  INV  statement. 


Format 

real-var  =  DET 

/ 

Syntax  Rules 

None. 

Remarks 


1.  When  a  matrix  is  inverted  with  the  MAT  INV  statement, 
BASIC-PLUS-2  calculates  the  determinant  as  a  by-product  of  the 
inversion  process.  The  DET  function  retrieves  this  value. 

2.  If  your  program  does  not  contain  a  MAT  INV  statement,  the  DET 
function  returns  a  value  of  zero. 

3.  The  value  returned  by  the  DET  function  is  a  floating-point  value  of 
the  default  size. 
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DET 


Example 


10  MAT  INPUT  first.arrayO.S) 

MAT  PRINT  lir8t_array; 

PRINT 

MAT  inv_array  *  INV  (first.array) 
determinant  »  DET 
MAT  PRINT  inv.array; 

PRINT 

PRINT  determinant 
PRINT 

MAT  mult .array  »  first .array  *  inv.array 
MAT  PRINT  mult.array; 

Output 

?  1.0, 0.0. 1.0, 0.0.1 
10  0 
0  10 
0  0  1 

10  0 
0  10 
0  0  1 

1 

10  0 
0  10 
0  0  1 
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DIF$ 


The  DIF$  function  returns  a  numeric  string  whose  value  is  the  difference 
between  two  numeric  strings. 


Format 

str-var  =  D\f$(str-exp1,  str-exp2} 


Syntax  Rules 

Each  str-exp  can  contain  up  to  54  ASCII  digits,  an  optional  decimal  point, 
and  an  optional  leading  sign. 


Remarks 


1.  BASIC-PLUS-2  subtracts  str-exp2  from  str-expl  and  stores  the  result  in 
str-var. 

2.  The  difference  between  two  integers  takes  the  precision  of  the  larger 
integer. 

3.  The  difference  between  two  decimal  fractions  takes  the  precision  of 
the  more  precise  fraction,  unless  trailing  zeros  generate  that  precision. 

4.  The  difference  between  two  floating-point  numbers  takes  precision  as 
follows; 

•  The  difference  of  the  integer  parts  takes  the  precision  of  the  larger 
part. 

•  The  difference  of  the  decimal  fraction  part  takes  the  precision  of 
the  more  precise  part. 

5.  BASIC-PLUS-2  truncates  leading  and  trailing  zeros. 
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DIFS 


Example 


10  PRINT  DIFS  ("689"."-231") 

Output 

920 
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DIMENSION 

The  DIMENSION  statement  creates  and  names  a  static,  dynamic,  or 
virtual  array.  The  array  subscripts  determine  the  dimensions  and  the  size 
of  the  array.  You  can  specify  the  data  type  of  the  array  and  associate  the 
array  with  an  I/O  channel. 

Format 

Nonvirtual,  Nonexecutable 

r  DIM  1 

1  DIMENSION  J 

^  {[  data-type  ]  array-name  ( int-const 

Executable 

r  DIM  1 

1  DIMENSION  j 

1  {[  data-type  ]  array-name  ( int-var, 

Virtual 

r  DIM  1 

1  DIMENSION  J 

1  #chnl-exp,  {  [  data-type  ]  array-name 
( int-const,  . . .  )  [=  int-const] . 

Syntax  Rules 


1.  An  array  name  in  a  DIM  statement  cannot  also  appear  in  a 
COMMON,  MAP,  or  DECLARE  statement. 

2.  Data-type  can  be  any  BASIC -PLUS-2  data  type  keyword.  Data  type 
keywords,  size,  range,  and  precision  are  listed  in  Table  1-2  in  this 
manual. 

3.  If  you  specify  a  data  type  and  the  array  name  ends  in  a  percent  sign 
( % )  or  dollar  sign  ( $ )  suffix  character,  the  variable  must  have  an 
INTEGER  or  STRING  data  type. 
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4.  If  you  do  not  specify  a  data  type,  the  array  name  determines  the  type 
of  data  the  array  holds.  If  the  array  name  ends  in  a  percent  sign,  the 
array  stores  integer  data  of  the  default  integer  size.  If  the  array  name 
ends  in  a  dollar  sign,  the  array  stores  string  data;  otherwise,  the  array 
stores  data  of  the  default  type  and  size. 

5.  An  array  can  have  up  to  eight  dimensions.  Nonvirtual  array  sizes  are 
limited  by  the  virtual  memory  limits  of  your  system. 

6.  Each  instance  of  int-const  or  int~vbl  within  the  parentheses  specifies 
the  upper  bound  of  an  array  dimension.  BASIC-PLUS-2  array  bounds 
must  be  in  the  range  0  to  32767. 

7.  Although  the  compiler  does  not  generate  an  error  for  subscript  values 
outside  of  these  ranges,  there  is  a  limit  to  the  amount  of  storage  your 
system  can  allocate.  Therefore,  very  large  arrays  can  cause  an  internal 
allocation  error  or  a  run-time  error. 

8.  Nonvirtual,  Nonexecutable 

•  When  all  the  dimension  specifications  are  integer  constants,  as 
in  DIM  A(15%,10%,20%),  the  DIM  statement  is  nonexecutable 
and  the  array  size  is  static.  A  static  array  cannot  appear  in  an¬ 
other  DIM  statement  because  BASIC-PLUS-2  determines  storage 
requirements  at  compilation  time. 

•  A  nonexecutable  DIM  statement  must  lexically  precede  any 
reference  to  the  array  it  dimensions.  That  is,  you  must  dimension 
a  static  array  before  you  can  reference  any  of  its  elements. 

9.  Virtual 

•  The  virtual  array  must  be  dimensioned  and  the  file  must  be  open 
before  you  can  reference  the  array. 

•  When  the  data  type  is  STRING,  the  Hnt~con$t  clause  specifies 
the  length  of  each  array  element.  The  default  string  length  is  16 
characters.  Virtual  string  array  lengths  are  rounded  to  the  next 
higher  power  of  2.  Therefore,  specifying  an  element  length  of  12 
results  in  an  actual  length  of  16.  For  example: 

DIM  #1,  STRING  vir.arraydoo)  «  12 

OPEN  "STATS. BAS"  FOR  OUTPUT  as  #1.  VIRTUAL 

10.  Executable 

When  any  of  the  dimension  specifications  are  integer  variables  as 
in  DIM  A(10%,20%,y%),  the  DIM  statement  is  executable  and  the 
array  is  dynamic.  A  dynamic  array  can  be  redimensioned  with  a 
DIM  statement  any  number  of  times  because  BASIC-PLUS-2  allocates 
storage  at  run  time  when  each  DIM  statement  is  executed. 
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Remarks 


1.  You  can  create  an  array  implicitly  by  referencing  an  array  element 
without  using  a  DIM  statement.  This  causes  BASIC-PLUS-2  to  create 
a  static  array  with  dimensions  of  (10),  (10,10),  (10,10,10),  and  so 
on,  depending  on  the  number  of  bounds  specifications  in  the  refer¬ 
enced  array  element.  You  cannot  create  virtual  or  executable  arrays 
implicitly. 

2.  The  lower  bound  of  an  array  is  always  zero,  rather  than  1.  Thus, 
A(10)  allocates  11  elements,  A(10,10)  allocates  121  elements,  and 
A(0,0,0)  allocates  1  element. 

3.  BASIC-PLUS-2  allocates  storage  for  arrays  by  row,  from  right  to  left. 

4.  Nonvirtual,  Nonexecutable 

•  You  can  declare  arrays  with  the  COMMON,  MAP,  and  DECLARE 
statements.  Arrays  so  declared  cannot  be  redimensioned  with 
the  DIM  statement.  Furthermore,  string  arrays  declared  with  a 
COMMON  or  MAP  statement  are  always  fixed  length. 

•  If  you  reference  an  array  element  declared  in  an  array  whose 
subscripts  are  larger  than  the  bounds  specified  in  the  DIM  state¬ 
ment,  BASIC-PLUS-2  signals  the  error  "Subscript  out  of  range" 
(ERR=55). 

•  Arrays  that  require  more  than  32767  bytes  of  storage  generate  the 
error  "Array  <name>  too  big." 

5.  Virtual 

•  When  the  rightmost  subscript  varies  faster  than  the  subscripts  to 
the  left,  fewer  disk  accesses  are  necessary  to  access  array  elements 
in  virtual  arrays. 

•  Using  the  same  DIM  statement  for  multiple  virtual  arrays  allocates 
all  arrays  in  a  single  disk  file.  The  arrays  are  stored  in  the  order  in 
which  they  were  declared. 

•  Any  program  or  subprogram  can  access  a  virtual  array  by  declar¬ 
ing  it  in  a  virtual  DIMENSION  statement.  For  example: 

DIM  *1,  A(10) 

DIM  *1,  B(10) 

In  this  example,  array  B  overlays  array  A.  You  must  specify  the 
same  channel  number,  data  types,  and  limits  in  the  same  order  as 
they  occur  in  the  DIM  statement  that  created  the  virtual  array. 
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•  BASIC-PLUS-2  stores  a  string  in  a  virtual  array  by  padding  it 
with  trailing  nulls  to  the  length  of  the  array  element.  It  removes 
these  nulls  when  it  retrieves  the  string  from  the  virtual  array. 
Remember  that  string  array  element  sizes  are  always  rounded  to 
the  next  power  of  2. 

•  On  RSX  systems,  the  OPEN  statement  for  a  virtual  array  must 
include  the  ORGANIZATION  VIRTUAL  clause  for  the  channel 
specified  in  the  DIMENSION  statement. 

•  BASIC-PLUS-2  does  not  initialize  virtual  arrays  and  treats  them  as 
statically  allocated  arrays.  You  cannot  redimension  virtual  arrays. 

•  Refer  to  the  BASIC~PLUS-2  User's  Guide  for  more  information  on 
virtual  arrays. 

6.  Executable 

•  You  create  an  executable,  dynamic  array  by  using  integer  variables 
for  array  bounds,  as  in  DIM  A(Y%,X%).  This  eliminates  the  need 
to  dimension  an  array  to  its  largest  possible  size.  Array  bounds 
in  an  executable  DIM  statement  can  be  constants  or  variables,  but 
not  expressions.  At  least  one  bound  must  be  a  variable. 

•  You  cannot  reference  an  array  named  in  an  executable  DIM 
statement  until  after  the  DIM  statement  executes. 

•  You  can  redimension  a  dynamic  array  to  make  the  bounds  of 
each  dimension  larger  or  smaller,  but  you  cannot  change  the 
number  of  dimensions.  For  example,  you  cannot  redimension  a 
four-dimensional  array  to  be  a  five-dimensional  array. 

•  The  executable  DIM  statement  cannot  be  used  to  dimension  virtual 
arrays,  arrays  received  as  formal  parameters,  or  arrays  declared  in 
COMMON,  MAP,  or  nonexecutable  DIM  statements. 

•  An  executable  DIM  statement  always  reinitializes  all  elements  in 
the  array  to  zero  (for  numeric  arrays)  or  to  the  null  string  if  string. 

•  If  you  reference  an  array  element  declared  in  an  executable  DIM 
statement  whose  subscripts  are  larger  than  the  bounds  specified 
in  the  last  execution  of  the  DIM,  BASIC-PLUS-2  signals  the  error 
"Subscript  out  of  range"  (ERR=55). 
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Examples 

Example  1 

10  {Nonvirtual,  Nonexecutable 

DIM  STRING  name.listdOO),  BYTE  age  (100) 

Example  2 

10  ! Virtual 

DIM  «1X.  STRING  name.listCSOO),  REAL  anount(lO.lO) 

Example  3 

10  {Executable 

DIM  DOUBLE  Inventory (base , markup) 

DIM  DOUBLE  inventory  (new.base , new_markup) 
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The  ECHO  function  causes  characters  to  be  echoed  at  a  terminal  that  is 
opened  on  a  specified  channel. 


Format 

int-var  =  ECHO(chnl-exp) 


Syntax  Rules 

Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  an  open  terminal.  It  cannot  be  preceded  by  a  number 
sign  (#). 


Remarks 


1.  The  ECHO  function  is  the  complement  of  the  NOECHO  function; 
each  function  disables  the  effect  of  the  other. 

2.  The  ECHO  function  has  no  effect  on  an  unopened  channel. 

3.  The  ECHO  function  always  returns  a  value  of  zero. 


Example 


10  DECLARE  INTEGER  Y,  k 

STRING  pass.word 

Y  «  NOECHO (0%) 

SET  NO  PROMPT 

INPUT  "Enter  your  password:  ";pass_word 

Y  *  ECH0(O%) 

IF  pass.word  *  "Darlene" 

THEN 

PRINT  CR+LF+"Y0U  ARE  CORRECT  !" 

END  IF 
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Output 

Enter  your  password? 
YOU  ARE  CORRECT  ! 
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EDITS 


The  EDITS  function  performs  one  or  more  string  editing  functions,  de¬ 
pending  on  the  value  of  its  integer  argument. 


Format 

str-var  =  Vin%(str-exp,  int-exp) 


Syntax  Rules 

None. 


Remarks 


1.  BASIC-PLUS-2  edits  str-exp  to  produce  str-var. 

2.  The  editing  that  BASIC-PLUS-2  performs  depends  on  the  value  of 
int-exp.  Table  4-3  describes  EDITS  values  and  functions. 

3.  All  values  are  additive.  For  example,  you  can  perform  the  editing 
functions  of  values  8,  16,  and  32  by  specifying  a  value  of  56.  You  can 
also  specify  the  values  in  an  expression,  for  example, 

8%  +  16%  +  32%.  Specifying  editing  values  as  an  expression  elimi¬ 
nates  human  error. 

4.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 
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Table  4-3;  EDIT$  Values _ 

Value  Function 

1  Discards  each  character's  parity  bit  (bit  7) 

2  Discards  all  spaces  and  tabs 

4  Discards  all  carriage  returns  <CR>  ,  line  feeds  <LF>  ,  form  feeds 

<FF>  ,  deletes  <DEL>  ,  escapes  <ESC>  ,  and  nulls  <NUL> 

8  Discards  leading  spaces  and  tabs 

16  Converts  multiple  spaces  and  tabs  to  a  single  space 

32  Converts  lowercase  letters  to  uppercase  letters 

64  Converts  left  bracket  to  left  parenthesis  (  [  to  (  )  and  right  bracket  to 

right  parenthesis  (  ]  to  )  ) 

128  Discards  trailing  spaces  and  tabs  (same  as  TRM$  function) 

256  Suppresses  all  editing  for  characters  within  quotation  marks;  if  the 

string  has  only  one  quotation  mark,  BASIC-PLUS-2  suppresses  all 
editing  for  the  characters  following  the  quotation  mark 


Example 


10  DECLARE  STRING  old.strlng,  new.strlng 

old.strlng  *  "a  value  of  32  converts  lowercase  letters  to  uppercase" 
new.strlng  «  EDIT$ (old.strlng. 32) 

PRINT  new.strlng 

Output 

A  VALUE  OF  32  CONVERTS  LOWERCASE  LETTERS  TO  UPPERCASE 
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END 


The  END  statement  marks  the  physical  and  logical  end  of  a  main  program, 
a  program  module,  or  a  block  of  statements. 


Format 

END  [block] 


block: 


'  Dif[exp] 

FUNCTION/ exp  ] 

PROGRAM 

SELECT 

SUB 


Syntax  Rules 


1.  The  END  statement  with  no  block  keyword  marks  the  end  of  a  main 
program.  The  END  or  END  PROGRAM  statement  must  be  the  last 
statement  on  the  last  lexical  line  of  the  main  program. 

2.  The  END  statement  followed  by  a  block  keyword  marks  the  end  of  a 
program,  a  BASIC-PLUS-2  SUB,  or  FUNCTION  subprogram,  a  DEF, 
an  IF,  a  PROGRAM,  or  a  SELECT  statement  block. 

3.  'The  END  block  statement  must  be  the  lexically  last  statement  in  a 
subprogram  or  statement  block  and  must  match  the  statement  that 
established  the  subprogram  or  statement  block. 
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Remarks 


1.  END  DEF  and  END  FUNCTION 

•  When  BASIC-PLUS-2  executes  an  END  DEF  or  an  END 
FUNCTION  statement,  it  returns  the  function  value  to  the  state¬ 
ment  that  invoked  the  function  and  releases  all  storage  associated 
with  the  DEF  or  FUNCTION. 

•  If  you  specify  an  optional  expression  with  the  END  DEF  or 
END  FUNCTION  statement,  the  expression  must  be  compatible 
with  the  DEF  or  FUNCTION  data  type.  The  expression  is  the 
function  result  unless  an  EXIT  DEF  or  EXIT  FUNCTION  statement 
is  executed.  This  expression  supersedes  all  function  assignments. 

•  The  END  DEF  statement  restores  the  error  handler  in  effect  when 
the  DEF  was  invoked.  This  is  not  true  of  the  DEF*  statement 
because  error  handling  in  a  DEF*  statement  is  global. 

•  The  END  FUNCTION  statement  does  not  affect  I/O  operations  or 
files. 

2.  END  PROGRAM 

•  The  END  PROGRAM  statement  allows  you  to  end  a  program 
module. 

•  You  can  specify  an  END  PROGRAM  statement  without  a  match¬ 
ing  PROGRAM  statement. 

3.  END  SUB 

•  The  END  SUB  statement  does  not  affect  I/O  operations  or  files. 

•  The  END  SUB  statement  releases  the  storage  allocated  to  local 
variables  and  returns  control  to  the  calling  program. 

•  The  END  SUB  statement  cannot  be  executed  in  an  error  handler 
unless  the  END  SUB  is  in  a  subprogram  called  by  the  error 
handler  of  another  routine. 

•  The  END  SUB  statement  restores  the  error  handler  in  effect  when 
the  SUB  was  invoked. 

4.  When  an  END  or  END  PROGRAM  statement  marking  the  end  of  a 

main  program  executes,  BASIC-PLUS-2  closes  all  files  and  releases  all 

program  storage. 

5.  If  you  use  ON  ERROR  error  handling,  you  must  clear  any  errors  with 

the  RESUME  statement  before  executing  an  END  PROGRAM, 

END  SUB,  or  END  FUNCTION  statement. 
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6.  Except  for  the  END  PROGRAM  statement,  BASIC-PLUS-2  signals 
an  error  when  a  program  contains  an  END  block  statement  with  no 
corresponding  and  preceding  block  keyword. 


Example 


10  INPUT  "Guess  a  number"; AX 
IF  AX  *  24 
THEN 

PRINT.  "YOU  GUESSED  IT!" 

END  IF 

IF  AX  <  24 
THEN 

PRINT.  "BIGGER  IS  BETTER!" 

GOTO  10 
END  IF 

IF  AX  >  24 
THEN 

PRINT.  "SMALLER  IS  BETTER!" 
GOTO  10 

END  IF 
END  PROGRAM 
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ERL 


The  ERL  function  returns  the  number  of  the  BASIC  line  where  the  last 
error  occurred. 


Format 

int-var  =  ERL 

Syntax  Rules 

None. 


Remarks 


1.  The  value  of  int-var  returned  by  the  ERL  function  is  a  WORD  integer. 

2.  If  the  ERL  function  is  used  before  an  error  occurs  or  after  an  error  is 
handled  with  a  RESUME  statement,  the  results  are  undefined. 

3.  The  ERL  function  overrides  the  /NOLINE  qualifier.  If  a  program 
compiled  with  the  /NOLINE  qualifier  in  effect  contains  an  ERL 
function,  BASIC-PLUS-2  signals  the  warning  message  "ERL  overrides 
NOLINE." 


Example 


100  IF  ERL  *  20 
THEN 

PRINT  "Invalid  input... try  again" 
RETRY 
ELSE 

PRINT  "UNEXPECTED  ERROR" 
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ERM$ 


The  ERN$  function  returns  the  name  of  the  main  program  or  subprogram 
that  was  executing  when  the  last  error  occurred. 


Format 

str-var  =  ERN$ 


Syntax  Rules 

None. 


Remarks 

If  the  ERN$  function  executes  before  an  error  occurs,  ERN$  is  undefined. 
When  an  error  occurs,  ERN$  is  set  to  the  name  of  the  module  that  caused 
the  error. 


Example 


10  ON  ERROR  GOTO  20 
DECLARE  LONG  Int.exp 
16  INPUT  "Enter  an  number" ; int.exp 
PRINT  DateKint.exp) 

GOTO  30 

20  PRINT  'Error  in  module ERN$ 
RESUME  15 
30  END 

Output 

Enter  a  number?  ABCD 
Error  in  module  DATE 
Enter  a  number?  0 
21 -May-86 
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The  ERR  function  returns  the  error  number  of  the  current  run-time  error. 


Format 

int-var  =  ERR 


Syntax  Rules 

None. 


Remarks 


•  The  value  of  int-var  returned  by  the  ERR  function  is  always  a  WORD 
integer. 

•  If  the  ERR  function  is  used  before  an  error  occurs  or  after  an  error  is 
handled  with  a  RESUME  statement,  the  results  are  undefined. 

•  See  the  BASIC-PLUS-2  User's  Guide  for  a  list  of  BASIC-PLUS-2  run¬ 
time  errors  and  their  numbers. 


Example 


10  PRINT  "Error  number"; ERR 

IF  ERR  -  50  THEN  PRINT  "DATA  FORMAT  ERROR" 
ELSE  PRINT  "UNEXPECTED  ERROR" 

END  IF 
RESUME 
END 
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The  ERT$  function  returns  explanatory  text  associated  with  an  error 
number. 


Format 

str-var  =  Ef{J$(int-exp) 


Syntax  Rules 

Int-exp  is  a  BASIC-PLUS-2  error  number.  The  error  number  must  be  in 
the  range  0  through  255. 


Remarks 


1.  The  ERT$  function  can  be  used  at  any  time  to  return  the  text  associ¬ 
ated  with  a  specified  error  number. 

2.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 


Example 


20  PRINT  "Error  number"; ERR 
PRINT  ERTKERR) 

RETRY 
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The  EXIT  statement  lets  you  exit  from  a  main  program,  a  SUB,  or 
FUNCTION  subprogram,  a  multi-line  DEF,  or  a  statement  block. 


Format 

EXIT  block 


block: 


'  DEf[exp] 
fUfiCmm  exp  ] 
SUB 

PROGRAM 

.  label 


Syntax  Rules 

1.  The  DEF,  FUNCTION,  SUB,  and  PROGRAM  keywords  specify  the 
type  of  subprogram,  or  multi-line  DEF  from  which  BASIC-PLUS-2  is 
to  exit. 

2.  If  you  specify  an  optional  expression  with  the  EXIT  DEF  statement 
or  with  the  EXIT  FUNCTION  statement,  the  expression  becomes  the 
function  result  and  supersedes  any  function  assignment.  It  also  over¬ 
rides  any  expression  specified  on  the  END  DEF  or  END  FUNCTION 
statement.  Note  that  the  expression  must  be  compatible  with  the 
FUNCTION  or  DEF  data  type. 

3.  Label  specifies  a  statement  label  for  an  IF,  SELECT,  FOR,  WHILE,  or 
UNTIL  statement  block. 
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Remarks 


1.  An  EXIT  SUB,  EXIT  FUNCTION,  EXIT  PROGRAM,  or  EXIT  DEF 
statement  is  equivalent  to  an  unconditional  branch  to  an  equivalent 
END  statement.  Control  then  passes  to  the  statement  that  invoked 
the  DEF  or  to  the  statement  following  the  statement  that  called  the 
subprogram. 

2.  The  EXIT  PROGRAM  statement  causes  BASIC-PLUS-2  to  exit  from  a 
main  program  module. 

3.  BASIC-PLUS-2  allows  you  to  specify  an  EXIT  PROGRAM  statement 
without  a  matching  PROGRAM  statement. 

4.  The  EXIT  label  statement  is  equivalent  to  an  unconditional  branch  to 
the  first  statement  following  the  end  of  the  IF,  SELECT,  FOR,  WHILE, 
or  UNTIL  statement  labeled  by  the  specified  label. 

5.  An  EXIT  FUNCTION,  EXIT  SUB  or  EXIT  PROGRAM  statement  cannot 
be  used  within  a  multi-line  DEF  function. 

6.  When  the  EXIT  FUNCTION,  EXIT  SUB  or  EXIT  PROGRAM  state¬ 
ment  executes,  BASIC-PLUS-2  releases  all  storage  allocated  to  local 
variables  and  returns  control  to  the  calling  program. 


Example 


10  DEF  factorial (X) 

EXIT  DEF  1  if  X  »  0 
END  DEF  (X  ♦  factorial (X  -1)) 
20  PRINT  "6!  -  ";factorial(5) 

Output 

6!  *  120 
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The  EXP  function  returns  the  value  of  the  mathematical  constant  c  raised 
to  a  specified  power. 


Format 

real-var  =  EXP  (real-exp) 


Syntax  Rules 

None. 


Remarks 


1.  The  EXP  function  returns  the  value  of  e  raised  to  the  power  of  real-exp. 

2.  BASlC-PLUS-2  expects  the  argument  of  the  EXP  function  to  be  a  real 
expression.  When  the  argument  is  a  real  expression,  BASlC-PLUS-2 
returns  a  value  of  the  same  floating-point  size.  When  the  argument 
is  not  a  real  expression,  BASlC-PLUS-2  converts  the  argument  to 
the  default  floating-point  size  and  returns  a  value  of  the  default 
floating-point  size. 

3.  EXP  allows  arguments  between  -88  and  88.  When  the  argument 
exceeds  the  upper  limit  of  this  range,  BASIC-PLUS-2  signals  an  error. 
When  the  argument  exceeds  the  lower  limit  of  this  range,  the  EXP 
function  returns  a  zero  and  BASIC-PLUS-2  does  not  signal  an  error. 
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Example 


10  DECLARE  SINGLE  nim.val 
num.val  *  EXP (4. 6) 
PRINT  num.val 

Output 

99.4843 
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The  EXTERNAL  statement  declares  constants,  variables,  functions,  and 
subroutines  external  to  your  program.  You  can  describe  parameters  for 
external  functions  and  subroutines. 


Format 

External  Constants 

EXTERNAL  data-type  CONSTANT  const-name.  . . . 

External  Variables 
EXTERNAL  data-type  unsubs-var,  . . . 

External  Functions 

EXTERNAL  data-type  FUNCTION  {  func-name  [ pass-mech  ] 


[  ( external-param 


External  Subroutines 

EXTERNAL  SUB  (  sub-name  [  pass-mech  ]  [  ( external-param 


external-param:  [ param-data-type ] [Q\M( [,]  . . .  I ] [= int-const ] [ pass-mech ] 
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Syntax  Rules 


1.  The  name  of  an  external  constant,  variable,  function,  or  subroutine 
can  be  from  one  through  six  characters. 

2.  For  all  external  routine  declarations,  the  name  must  be  a  valid 
BASIC-PLUS-2  identifier  and  must  not  be  the  same  as  any  other  SUB, 
FUNCTION,  or  PROGRAM  name. 

3.  The  first  character  of  an  unquoted  name  must  be  an  alphabetic  char¬ 
acter.  The  remaining  characters,  if  present,  can  be  any  combination  of 
letters,  digits  (0  through  9),  dollar  signs  ( $ ),  and  periods  ( . ). 

4.  External  Constants 

For  external  constants,  data-type  must  be  WORD  or  INTEGER  (if  the 
default  size  is  WORD). 

5.  External  Variables 

For  external  variables,  data  type  can  be  any  valid  numeric  data  type. 

6.  External  Functions  and  Subroutines 

•  For  external  functions  and  subroutines,  the  data  type  can  be  any 
valid  BASIC-PLUS-2  data  type.  See  Table  1-2  in  this  manual  for 
more  information  on  data  type  size,  range  and  precision. 

•  For  external  functions,  the  data  type  that  precedes  the  keyword 
FUNCTION  defines  the  data  type  of  the  function  result. 

•  External-param  defines  the  form  of  the  arguments  passed  to  the 
external  function  or  subprogram.  Empty  parentheses  indicate 
that  the  subprogram  expects  zero  parameters.  Missing  paren¬ 
theses  indicate  that  the  EXTERNAL  statement  does  not  define 
parameters. 

•  You  can  specify  up  to  32  formal  parameters  for  BASIC-PLUS-2 
subprograms  and  255  formal  parameters  for  other  programs. 

•  Param-data-type  specifies  the  data  type  of  a  parameter.  If  you  do 
not  specify  a  data  type,  parameters  are  of  the  default  data  type 
and  size. 

•  Quoted  names  are  allowed  for  external  subroutines  only.  Quoted 
names  can  be  any  combination  of  letters,  digits,  dollar  signs, 
periods,  and  spaces. 
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•  Pass-mech  specifies  how  parameters  are  to  be  passed  to  the 
function  or  subroutine. 

—  A  pass-mech  clause  outside  the  parentheses  applies  to  all 
parameters. 

—  A  pass-mech  clause  inside  the  parentheses  overrides  the 

previous  pass-mech  and  applies  only  to  the  specific  parameter. 

7.  Declaring  Array  Dimensions 

The  DIM  keyword  indicates  that  the  parameter  is  an  array.  Commas 
specify  array  dimensions.  The  number  of  dimensions  is  equal  to  the 
number  of  commas  plus  1.  For  example: 

10  EXTERNAL  STRING  FUNCTION  new  (DOUBLE.  STRING  DIM(,),  DIMO) 

This  Statement  declares  a  function  named  new  that  has  three  param¬ 
eters.  The  first  is  a  double-precision  floating-point  value,  the  second 
is  a  two-dimensional  string  array,  and  the  third  is  a  one-dimensional 
string  array.  The  function  returns  a  string  result. 


Remarks 


1.  The  EXTERNAL  statement  must  precede  any  program  reference  to  the 
constant,  variable,  function,  or  subroutine  declared  in  the  statement. 

2.  The  EXTERNAL  statement  is  not  executable. 

3.  A  name  declared  in  an  EXTERNAL  CONSTANT  statement  can  be 
used  in  any  nondeclarative  statement  as  if  it  were  a  constant. 

4.  A  name  declared  in  an  EXTERNAL  FUNCTION  statement  can  be  used 
as  a  function  invocation  in  an  expression.  In  addition,  you  can  invoke 
a  function  with  the  CALL  statement  unless  the  function  data  type  is 
STRING  or  RFA. 

5.  A  name  declared  in  an  EXTERNAL  SUB  statement  can  be  used  in  a 
CALL  statement. 

6.  The  optional  pass-mech  clauses  in  the  EXTERNAL  FUNCTION  and 
EXTERNAL  SUB  statements  tell  BASIC-PLUS-2  how  to  pass  ar^- 
ments  to  a  non-BASIC  function  or  subprogram.  Table  4-1  describes 
BASIC-PLUS-2  parameter-passing  mechanisms.  Note  that  you  cannot 
specify  a  pass-mech  when  invoking  a  BASIC-PLUS-2  subprogram. 

•  BY  VALUE  specifies  that  BASIC-PLUS-2  passes  the  argument's 
16-bit  value. 
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•  BY  REF  specifies  that  BASIC-PLUS-2  passes  the  argument's 
address.  This  is  the  default  for  all  arguments  except  strings  and 
entire  arrays.  If  you  know  the  size  of  string  parameters  and 
the  dimensions  of  array  parameters,  you  can  improve  run-time 
performance  by  passing  strings  and  arrays  by  reference. 

•  BY  DESC  specifies  that  BASIC-PLUS-2  passes  the  address  of 
a  BASIC-PLUS-2  descriptor.  For  information  about  the  format 
of  a  BASIC-PLUS-2  descriptor  for  strings  and  arrays,  see  the 
BASIC-PLUS-2  User's  Guide. 

7.  When  invoked,  the  arguments  passed  to  external  functions  and 
subroutines  should  match  the  external  parameters  declared  in  the 
EXTERNAL  FUNCTION  or  EXTERNAL  SUB  statement  in  number, 
type,  and  passing  mechanism.  BASIC-PLUS-2  forces  arguments  to 
be  compatible  with  declared  parameters.  If  they  are  not  compatible, 
BASIC-PLUS-2  signals  an  error. 


Examples 


Example  1 

10  ! External  Constant 

EXTERNAL  WORD  CONSTANT  lE.SUC 

Example  2 

10  ! External  Variable 

EXTERNAL  WORD  SYSNUM 

Example  3 

10  ! External  Function 

EXTERNAL  DOUBLE  FUNCTION  USRt2 (WORD, LONG) 

Example  4 

10  ! External  Subroutine 

EXTERNAL  SUB  calc  BY  DESC  (STRING  DIM(.).  BYTE  BY  REF) 
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The  FIELD  statement  dynamically  associates  string  variables  with  all  or 
parts  of  a  record  buffer.  FIELD  statements  do  not  move  data.  Instead, 
they  permit  direct  access  through  string  variables  to  sections  of  a  specified 
record  buffer. 

NOTE 

The  FIELD  statement  is  supported  only  for  compatibility  with 
BASIC-PLUS.  Because  data  defined  in  the  FIELD  statement 
can  be  accessed  only  as  string  data,  you  must  use  the  CVTxx 
functions  to  process  numeric  data;  therefore,  you  must  convert 
string  data  to  numeric  after  you  move  it  from  the  record 
buffer.  Then,  after  processing,  you  must  convert  numeric 
data  back  to  string  data  before  transferring  it  to  the  record 
buffer.  It  is  recommended  that  you  use  the  BASIC-PLUS-2 
dynamic  mapping  feature  or  multiple  maps  instead  of  the 
FIELD  statement  and  CVTxx  functions. 


Format 

FIELD  #chnl-exp,  int-exp  AS  str-var[ ,  int-exp  AS  str-var  ]  . . . 


Syntax  Rules 


1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#).  A  file  must  be  open  on  the  specified  channel  or 
BASIC-PLUS-2  signals  an  error. 

2.  Int-exp  specifies  the  number  of  characters  in  str-var. 
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Remarks 


1.  A  FIELD  statement  is  executable.  You  can  change  a  buffer  description 
at  any  time  by  executing  another  FIELD  statement.  For  example: 

FIELD  «iy..  40y.  AS  whole.fieldl 

FIELD  »iy..  10%  AS  A$.  10%  AS  B$.  10%  AS  C$.  10%  AS  D$ 

The  first  FIELD  statement  associates  the  first  40  characters  of  a  buffer 
with  the  variable  whole— field$.  The  second  FIELD  statement  associates 
the  first  10  characters  of  the  same  buffer  with  A$,  the  second  10 
characters  with  B$,  and  so  on.  Later  program  statements  can  refer  to 
any  of  the  variables  named  in  the  FIELD  statements  to  access  specific 
portions  of  the  buffer. 

2.  You  cannot  define  virtual  array  strings  as  string  variables  in  a  FIELD 
statement. 

3.  The  FIELD  statement  is  also  described  in  the  BASIC-PLUS  Language 
Manual 


Example 


10  FIELD  *8%.  2%  AS  U$.  2%  AS  CL$,  4X  AS  X$,  4%  AS  Y$ 
LSET  0$  «  CVn$(UX) 

LSET  CL$  -  CVTXKCLX) 

LSET  X$  -  CVTF$(X) 

LSET  Y$  •  CVTFI(Y) 

UX  «  CVT$X(U$) 

CLX  *  CVT$X(CL$) 

X  «  CVT$F(X8) 

Y  =  CVT$F(Y$) 
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The  FIND  statement  locates  a  specified  record  in  a  disk  file  and  makes 
it  the  current  record  for  a  GET,  UPDATE,  or  DELETE  operation.  FIND 
statements  are  valid  on  RMS  sequential,  relative,  and  indexed  files. 


Format 

FIND  #chnl-exp  [  .position-clause  ] 


(  RFA  rfa-exp 

position-clause: 

<  RECORD  num-exp 

1  KEY#  key-clause 

key-clause: 

int-expl  rel-op  key-exp 

(  EQ  ) 

rel-op: 

GE 

1  GT  J 

key-exp: 

f  int-exp2  1 

1  str-exp  j 

Syntax  Rules 


1.  ChnUexp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 
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Remarks 


1.  Position-clause 

•  Position-clause  specifies  the  position  of  a  record  in  a  file. 
BASIC-PLUS-2  signals  an  error  if  you  specify  a  position-clause  and 
the  channel  is  not  associated  with  a  disk  file.  If  you  do  not  specify 
a  position-clause,  FIND  locates  records  sequentially.  Sequential 
record  access  is  valid  on  all  RMS  files. 

•  The  RFA  position-clause  allows  you  to  randonUy  locate  records  by 
specifying  the  record  file  address  (RFA)  of  a  record.  You  specify 
the  disk  address  of  a  record,  and  RMS  locates  the  record  at  that 
address.  All  file  organizations  can  be  accessed  by  RFA. 

Rfa-exp  in  the  RFA  position-clause  is  a  variable  of  the  RFA  data 
type  that  specifies  the  record's  file  address.  Note  that  an  RFA 
expression  can  only  be  a  variable  of  the  RFA  data  type  or  the 
GETRFA  function.  Use  the  GETRFA  function  to  find  the  RFA  of  a 
record. 

•  The  RECORD  position-clause  allows  you  to  randomly  locate 
records  in  relative  and  sequential  fixed  files  by  specifying  the 
record  number. 

—  Num-exp  in  the  RECORD  position-clause  specifies  the  number 
of  the  record  you  want  to  locate.  It  must  be  between  1  and 
the  number  of  the  record  with  the  highest  number  in  the  file. 

—  When  you  specify  a  RECORD  clause,  chnl-exp  must  be  a 
channel  associated  with  an  open  relative  or  sequential  fixed 
file. 

•  The  KEY  position-clause  allows  you  to  randomly  locate  records  in 
indexed  files  by  specifying  a  key  of  reference,  a  relational  test,  and 
a  key  value. 

2.  Key-clause 

•  In  a  key-clause,  int-expl  is  the  target  key  of  reference.  It  must  be 
an  integer  in  the  range  of  zero  through  the  highest-numbered  key 
for  the  file.  The  primary  key  is  #0,  the  first  alternate  key  is  #1,  the 
second  alternate  key  is  #2,  and  so  on.  Int-expl  must  be  preceded 
by  a  number  sign  (#)  or  BASIC-PLUS-2  signals  an  error. 

•  When  you  specify  a  key-clause,  the  specified  channel  must  be  a 
channel  associated  with  an  open  indexed  file. 
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3.  Rel-op 

•  Rel-op  is  a  relational  operator  that  specifies  how  key-exp  is  to  be 
compared  with  int-expl  in  the  key-clause. 

—  EQ  means  equal  to 
—  GE  means  greater  than  or  equal  to 
—  GT  means  greater  than 

•  A  successful  random  FIND  operation  by  key  locates  the  first 
record  whose  key  satisfies  the  key-clause  comparison: 

—  With  an  equal  to  (EQ)  key  match,  a  successful  FIND  locates 
the  first  record  in  the  file  that  equals  the  key  value  specified  in 
key-exp.  If  the  characters  specified  by  a  str-exp  key  expression 
are  less  than  the  key  length,  characters  specified  by  str-exp  are 
matched  approximately  rather  than  exactly.  For  example,  if 
you  specify  "ABC"  and  the  key  length  is  six  characters, 
BASlC-PLUS-2  locates  the  first  record  that  begins  with  ABC.  If 
you  specify  "ABCABC",  BASIC-PLUS-2  locates  only  a  record 
with  the  key  "ABCABC".  If  no  match  is  possible, 
BASIC-PLUS-2  signals  the  error  "Record  not  found" 
(ERR=155). 

—  If  you  specify  a  greater  than  or  equal  to  (GE)  key  match,  a 
successful  FIND  locates  the  first  record  that  equals  the  key 
value  specified  in  key-exp.  If  no  exact  match  is  possible, 
BASIC-PLUS-2  selects  the  next  record  in  the  key  sort  order 
with  a  higher  key  value.  If  no  such  record  exists, 
BASIC-PLUS-2  signals  the  error  "Record  not  found" 
(ERR=155). 

—  With  a  greater  than  (GT)  key  match,  a  successful  FIND  lo¬ 
cates  the  first  record  with  a  value  greater  than  the  key  value 
specified  in  key-exp.  If  no  such  record  exists,  BASIC-PLUS-2 
signals  the  error  "Record  not  found"  (ERR=155). 

4.  Key-exp 

•  Int-expl  specifies  an  integer  value  to  be  compared  with  the  key 
value  of  a  record. 

•  Str-exp  specifies  a  string  value  to  be  compared  with  the  key  value 
of  a  record.  Str-exp  can  contain  fewer  characters  than  the  key  of 
the  record  you  want  to  locate,  but  cannot  be  a  null  string. 

5.  FIND  does  not  transfer  any  data  to  the  record  buffer.  To  access  the 

contents  of  a  record,  use  the  GET  statement. 

6.  The  file  specified  by  chnl-exp  must  be  open  with  ACCESS  READ  or 

MODIFY  before  your  program  can  execute  a  FIND  statement. 
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7.  A  successful  sequential  FIND  operation  updates  both  the  current 
record  pointers  and  next  record  pointers. 

•  For  sequential  files,  a  successful  FIND  operation  locates  the  next 
sequential  record  (the  record  pointed  to  by  the  next  record  pointer) 
in  the  file,  changes  the  current  record  pointer  to  the  record  just 
found,  and  sets  the  next  record  pointer  to  the  next  sequential 
record.  If  the  current  record  pointer  points  to  the  last  record  in  a 
file,  a  sequential  FIND  operation  causes  BASIC-PLUS-2  to  signal 
"End  of  file  on  device"  (ERR=11). 

•  For  relative  files,  a  successful  FIND  operation  locates  the  record 
that  exists  with  the  next  higher  record  number  (or  cell  number), 
makes  it  the  current  record,  and  sets  the  next  record  pointer  to  the 
record  with  the  next  higher  record  number. 

•  For  indexed  files,  a  successful  FIND  operation  locates  the  next 
logical  record  in  the  current  key  of  reference,  makes  this  the 
current  record,  and  changes  the  next  record  pointer  to  the  next 
logical  record  in  the  current  key  of  reference. 

8.  A  successful  random  access  FIND  operation  by  RFA  or  by  record 
changes  the  current  record  pointer  to  the  record  specified  by  rfa-exp  or 
int-exp,  but  leaves  the  next  record  pointer  unchanged. 

9.  A  successful  random  access  FIND  operation  by  key  changes  the 
current  record  pointer  to  the  first  record  whose  key  satisfies  the 
key-clause  comparison,  and  the  next  record  pointer  to  the  record  with 
the  next  value  in  the  key  sort  order. 

10.  When  a  random  access  FIND  operation  by  RFA,  record,  or  key  is 
not  successful,  BASIC-PLUS-2  signals  the  error  "Record  not  found" 
(ERR=155).  The  values  of  the  current  record  pointer  and  next  record 
pointer  are  undefined. 

11.  You  should  not  use  a  FIND  statement  on  a  terminal-format  or  virtual 
array  file. 

12.  When  you  access  a  shared  file,  a  successful  FIND  locks  the  record  or 
bucket  and  unlocks  the  previously  locked  record  or  bucket. 
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Example 


10  DECLARE  LONG  rec-num 

MAP  (cusrec)  WORD  cue.num  A 

STRING  cu8_nam*20 ,  cu8_add*20,  cu8_city*10,  cu8_2ip*9 

OPEN  "ACCT.DAT"  FOR  INPUT  AS  #1.  A 

RELATIVE  FIXED.  A 

ACCESS  MODIFY  A 

MAP  cu8rec 


INPUT  "Which  record  number  would  you  like  to  delete" ;rec_num 

FIND  »i.  RECORD  rec.num 

DELETE  il 

CLOSE  «1 

END 
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FIX 


The  FIX  function  truncates  a  floating-point  value  at  the  decimal  point  and 
returns  the  integer  portion  represented  as  a  floating-point  value. 


Format 

real-var  =  f\X(real-exp) 


Syntax  Rules 

None. 


Remarks 


1.  The  FIX  function  returns  the  integer  portion  of  a  floating-point  value, 
not  an  integer  value. 

2.  BASIC-PLUS-2  expects  the  argument  of  the  FIX  function  to  be  a  real 
expression.  When  the  argument  is  a  real  expression,  BASIC-PLUS-2 
returns  a  value  of  the  same  floating-point  size.  When  the  argument 
is  not  a  real  expression,  BASIC-PLUS-2  converts  the  argument  to 
the  default  floating-point  size  and  returns  a  value  of  the  default 
floating-point  size. 

3.  If  real-exp  is  negative,  FIX  returns  the  negative  integer  portion.  For 
example,  FIX(-5.2)  returns  -5. 


Example 


10  DECLARE  SINGLE  result 
result  «  FIX (-3. 333) 

PRINT  FIX(24.666).  result 

Output 

24  >3 
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FniEND 

The  FNEND  statement  is  a  synonym  for  END  DEE.  See  the  END  state¬ 
ment  for  more  information. 


Format 

FNEND  [exp] 
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FNEXIT 


The  FNEXIT  statement  is  a  synonym  for  the  EXIT  DEF  statement.  See  the 
EXIT  statement  for  more  information. 


Format 

FNEXIT  [exp] 
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FOR 

The  FOR  statement  repeatedly  executes  a  block  of  statements,  while  in¬ 
crementing  a  specified  control  variable  for  each  execution  of  the  statement 
block.  FOR  loops  can  be  conditional  or  unconditional,  and  can  modify 
other  statements. 


Format 

Unconditional 

FOR  num-unsubs-var  =  num-expl  TO  num-exp2  [  STEP  num-exp3  ] 

[  statement  ]... 

NEXT  num-unsubs-var 

Conditional 

FOR  num-unsubs-var  =  num-exp  1  [  STEP  num-exp3  ]  |  |  cond-exp 

[  statement  ]... 

NEXT  num-unsubs-var 

Unconditional  Statement  Modifier 

Statement  FOR  num-unsubs-var  =  num-expl  TO  num-exp2  [ STEP  num-exp3] 

Conditional  Statement  Modifier 

Statement  FOR  num-unsubs-var  =  num-expl  [  STEP  num-exp3 ]  |  |  cond-exp 
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Syntax  Rules 


1.  Num-unsuhs-var  must  be  a  numeric,  unsubscripted  variable. 

2.  Num-un$ubs~var  is  the  loop  variable.  It  is  incremented  each  time  the 
loop  executes. 

3.  In  unconditional  FOR  loops,  num-expl  is  the  initial  value  of  the  loop 
variable;  num-exp2  is  the  maximum  value. 

4.  In  conditional  FOR  loops,  num~expl  is  the  initial  value  of  the  loop 
variable,  while  the  cond-exp  in  the  WHILE  or  UNTIL  clause  is  the 
condition  that  controls  loop  iteration. 

5.  Num-exp3  in  the  STEP  clause  is  the  value  by  which  the  loop  variable 
is  incremented  after  each  execution  of  the  loop. 


Remarks 


1.  The  default  for  num-exp3  is  1  if  there  is  no  STEP  clause. 

2.  You  can  transfer  control  into  a  FOR  loop  only  by  returning  from  a 
function  invocation,  a  subprogram  call,  a  subroutine  call,  or  an  error 
handler  that  was  invoked  in  the  loop. 

3.  The  loop  variable  can  be  modified  inside  the  FOR  loop. 

4.  The  starting,  incrementing,  and  ending  values  of  a  loop  cannot  be 
changed  during  loop  execution. 

5.  When  an  unconditional  FOR  loop  ends,  the  loop  variable  contains  the 
value  last  used  in  the  loop,  not  the  value  that  caused  loop  termination. 

6.  BASIC-PLUS-2  converts  num-expl,  num-exp2,  and  num-exp3  to  the 
data  t)^e  of  the  loop  variable  before  storing  them. 

7.  If  the  loop  variable  exceeds  the  allowable  range  for  its  data  type, 
BASIC-PLUS-2  signals  the  error  "Integer  overflow,  FOR  loop" 
(ERR=60). 

8.  An  inner  loop  must  be  entirely  within  an  outer  loop;  the  loops  cannot 
overlap. 

•  There  is  a  limit  to  the  number  of  inner  loops  you  can  contain 
within  a  single  outer  loop.  This  number  varies  according  to  the 
complexity  of  the  loops.  If  you  exceed  the  limit,  BASIC-PLUS-2 
signals  the  error  message  "Program  structures  nested  too  deeply." 
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•  You  cannot  use  the  same  loop  variable  in  nested  FOR  loops.  For 
example,  if  the  outer  loop  uses  FOR  J  =  1  TO  10,  you  cannot  use 
the  variable  /  as  a  loop  variable  in  an  inner  loop. 

9.  During  each  iteration  of  a  conditional  loop,  BASIC -PLUS-2  tests  the 
value  of  cond-exp  before  it  executes  the  loop. 

•  If  you  specify  a  WHILE  clause  and  cond-exp  is  false  (value  zero), 
BASIC-PLUS-2  exits  from  the  loop.  If  the  cond-exp  is  true  (value 
nonzero),  the  loop  executes  again. 

•  If  you  specify  an  UNTIL  clause  and  cond-exp  is  true  (value 
nonzero),  BASIC-PLUS-2  exits  from  the  loop.  If  the  cond-exp 
is  false  (value  zero),  the  loop  executes  again. 

10.  When  FOR  is  used  as  a  statement  modifier,  BASIC-PLUS-2  executes 
the  statement  until  the  loop  variable  equals  or  exceeds  num-exp2  or 
until  the  WHILE  or  UNLESS  condition  is  satisfied. 

11.  Each  FOR  statement  must  have  a  corresponding  NEXT  statement 
or  BASIC-PLUS-2  signals  an  error.  (This  is  not  the  case  if  the  FOR 
statement  is  used  as  a  statement  modifier.) 


Examples 
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Example  1 

10  ! Unconditional 

DECLARE  LONG  course.num,  STRING  course.nam 

FOR  I  *  3  TO  12  STEP  3 

INPUT  "Course  number" ;cour8e_num 

INPUT  "Course  name" ;cour8e_nam 

NEXT  I 

Output  1 

Course  number?  221 

Course  name?  Botany 

Course  number?  231 

Course  name?  Organic  Chemistry 

Course  number?  237 

Course  name?  Life  Science  II 

Course  number?  244 

Course  name?  Programming  in  BASIC-PLUS-2 

Example  2 

10  ! Unconditional  Statement  Modifier 
DECLARE  INTEGER  counter 

PRINT  "This  is  an  unconditional  statement  modifier"  A 
FOR  counter  «  1  TO  3 
END 

Output  2 

This  is  an  unconditional  statement  modifier 
This  is  an  unconditional  statement  modifier 
This  is  an  unconditional  statement  modifier 

Example  3 

10  ! Conditional  Statement  Modifier 
DECLARE  INTEGER  counter,  A 
STRING  my_name 

INPUT  "Try  and  guess  my  name" ;my_name  FOR  counter  *  1  A 
UNTIL  my_name  »  "BASIC" 

PRINT  "You  guessed  it ! " 

Output  3 

Try  and  guess  my  name?  PASCAL 
Try  and  guess  my  name?  FORTRAN 
Try  and  guess  my  name?  BASIC 
You  guessed  it! 
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FORMATS 


The  FORMATS  function  converts  an  expression  to  a  formatted  string. 


Format 

sff-rar  =  FORMATS  str-exp) 


Syntax  Rules 

1.  The  rules  for  building  a  format  string  are  the  same  as  those  for  print¬ 
ing  numbers  with  the  PRINT  USING  statement.  See  the  description 
of  the  PRINT  USING  statement  for  more  information. 

2.  You  cannot  specify  the  FORMATS  function  in  a  PRINT  USING 
statement. 


Remarks 

None. 


Example 


10  DECLARE  STRING  result.  k 

INTEGER  nuffi.exp 
num.exp  *  12345 

result  *  FORMAT! (num_exp. ”##,###") 
PRINT  result 

Output 

12.345 
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FSP$ 


The  FSP$  function  returns  a  string  describing  an  open  file  on  a  specified 
channel. 


Format 

str-var  =  fSPt(chnl-exp) 


Syntax  Rules 

1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number.  You 
cannot  precede  the  chnl-exp  with  a  number  sign  (#). 

2.  A  file  must  be  open  on  chnl-exp. 

3.  The  FSP$  function  must  come  immediately  after  the  OPEN  statement 
for  the  file. 

4.  The  returned  string  is  28  bytes  long. 


Remarks 


1.  Table  4-4  describes  the  RMS  fields  and  their  corresponding  BYTE 
values. 

2.  Use  the  FSP$  function  with  files  opened  as  ORGANIZATION 
UNDEFINED.  Then  use  multiple  MAP  statements  to  interpret  the 
returned  data. 

3.  See  the  BASIC-PLUS-2  User's  Guide  and  the  RMS-11  documentation 
for  more  information  on  FSP$  values. 
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Table  4-4:  FSP$  Return  Values  and  Corresponding  RMS 


Fields 

Return  Value 

RMS  Field 

Description 

0 

RFM  +  ORG 

File  Organization  code  plus  record 
format  code 

1 

RAT 

Record  handling  mask 

2,3 

MRS 

Maximum  record  size  in  bytes 

4,5,6,7 

ALQ 

File  allocation  size 

8,9 

BLS  or  BKS 

Magtape  block  size  or  file  bucket  size 

10,11 

NA 

Number  of  indexed  keys 

12,13,14,15 

MRN 

Maximum  record  number 

16,17,18,19 

BKT 

Virtual  block  number  or  relative 
record  number 

Example 


10  MAP  (A)  STRING  A  «  28 

MAP  (A)  BYTE  org_rlm,  rat.  WORD  mrs.  LONG  alq,  k 
WORD  bka.bls.  num.keys , LONG  bkt  mrn. 

OPEN  "STUDENT. DAT"  FOR  INPUT  AS  #1%,  k 

ORGANIZATION  UNDEFINED.  k 

RECORDTYPE  ANY.  ACCESS  READ 
A  «  FSPKIX) 

PRINT  "RMS  organization  and  record  format  «  ";org_rfm 

PRINT  "RMS  record  attributes  *  ";rat 

PRINT  "RMS  maximum  record  size  *  ";mrs 

PRINT  "RMS  allocation  quantity  «  ":alq 

PRINT  "RMS  bucket  size  >  ":bks_bls 

PRINT  "Number  of  keys  *  ";num_keys 

PRINT  "RMS  maximum  record  number  >  ";mrn 

PRINT  "RMS  virtual  block  number  «  ":bkt 

Output 

RMS  organization  >  2 
RMS  record  attributes  «  2 
RMS  maximum  record  size  «  5 
RMS  allocation  quantity  *  1 
RMS  bucket  size  *  0 
Number  of  keys  *  0 
RMS  maximum  record  number  «  0 
RMS  virtual  block  number  «  1 
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FSS$ 


The  FSS$  function  scans  a  file  name  string  beginning  at  a  specified  posi¬ 
tion  and  returns  a  30-character  string  describing  the  file  name  and  status. 
Because  file  specifications  differ  from  system  to  system,  the  returned  string 
contains  system-specific  information. 


Format 

str-vbl  =  fSS%(str-vbl,int-vbl} 


Syntax  Rules 

1.  Str-vbl  names  the  file  name  string  to  be  scanned. 

2.  Int-vbl  specifies  the  character  position  at  which  scanning  starts. 


Remarks 


1.  If  you  specify  a  floating-point  variable  for  int-vbl,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 

2.  Str-vbl  is  a  30-character  string.  See  the  BASIC-PLUS-2  User's  Guide  for 
information  on  the  encoding  of  str-vbl. 

3.  See  the  BASIC-PLUS-2  User's  Guide  for  more  information  on  the  values 
returned  by  the  FSS$  function. 


Example 


100  Y$  >  FSS>(A$,BX) 
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FuniCTioni 


The  FUNCTION  statement  marks  the  beginning  of  a  FUNCTION  subpro¬ 
gram  and  defines  the  subprogram's  parameters. 


Format 

FUNCTION  data-type  func-name  [{[  formal-param  ],...)] 
[  statement  ]... 

j  END  FUNCTION  f  exp  7  1 
I  FUNCTIONEND/exp;  i 


formal  param:  [  data-type  ] 


unsubs-var 
array-name  ( 


int-const 


) 


Syntax  Rules 


1.  Func-name  names  the  FUNCTION  subprogram. 

2.  Func-name  can  have  from  one  through  six  characters.  The  first  char¬ 
acter  must  be  an  alphabetic  character.  The  remaining  characters  can 
be  any  combination  of  letters,  digits  (0  through  9),  dollar  signs  ( $ ) 
and  periods  ( . ),  with  the  exception  that  the  last  character  cannot  be  a 
dollar  sign  ( $ ). 

3.  Data-type  can  be  any  BASIC-PLUS-2  data  type  keyword.  Data  type 
keywords,  size,  range,  and  precision  are  listed  in  Table  1-2  in  this 
manual. 

4.  The  data  type  that  precedes  the  func-name  specifies  the  data  type  of 
the  value  returned  by  the  function. 

5.  Formal-param  specifies  the  number  and  type  of  parameters  for  the 
arguments  the  function  expects  to  receive  when  invoked. 

•  Empty  parentheses  indicate  that  the  function  has  no  parameters. 


4-104  Statements  and  Functions 


FUNCTION 


•  Data-type  specifies  the  data  type  of  a  parameter.  If  you  do  not 
specify  a  data  type,  parameters  are  of  the  default  data  type  and 
size.  When  you  do  specify  a  data  t5rpe,  all  following  parameters 
are  of  that  data  type  until  you  specify  a  new  data  type. 

•  Parameters  defined  in  formal-param  must  agree  in  number  and 
type  with  the  arguments  specified  in  the  function  invocation. 

•  You  can  specify  up  to  32  formal  parameters. 

6.  Exp  specifies  the  function  result  which  supersedes  any  function  assign¬ 
ment.  Exp  must  be  compatible  with  the  function's  data  type. 


Remarks 


1.  The  FUNCTION  statement  must  be  the  first  statement  in  the 
FUNCTION  subprogram. 

2.  Every  FUNCTION  statement  must  have  a  corresponding 
END  FUNCTION  or  FUNCTIONEND  statement. 

3.  Any  BASIC-PLUS-2  statement  except  END,  PROGRAM, 

END  PROGRAM,  SUB,  SUBEND,  END  SUB,  or  SUBEXIT  can  appear 
in  a  FUNCTION  subprogram. 

4.  FUNCTION  subprograms  must  be  declared  with  the  EXTERNAL 
statement  before  your  BASIC-PLUS-2  program  can  invoke  them. 

5.  All  variables  and  data,  except  virtual  arrays,  COMMON  areas,  MAP 
areas,  and  EXTERNAL  variables,  in  a  FUNCTION  subprogram  are 
local  to  the  subprogram. 

6.  BASIC-PLUS-2  initializes  local  numeric  variables  to  zero  and  lo¬ 
cal  string  variables  to  the  null  string  each  time  the  FUNCTION 
subprogram  is  invoked. 

7.  ON  ERROR  GO  BACK  is  the  default  error  handler  for  FUNCTION 
subprograms. 

8.  To  return  a  function  value,  either  assign  a  value  to  the  function  name 
or  specify  a  value  with  the  END  FUNCTION  or  EXIT  FUNCTION 
statement.  Note  that  you  can  only  assign  a  value  to  a  function  name 
while  inside  that  function  subprogram. 
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Example 


10  FWCTION  REAL  ephere.volume  (REAL  R) 
IF  R  <  0  THEN  EXIT  FUNCTION 
ephere.volume  *  4/3  ♦  PI  *R  **3 
END  FUNCTION 
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FuniCTioniEniD 


The  FUNCTIONEND  statement  is  a  synonym  for  the  END  FUNCTION 
statement.  See  the  END  statement  for  more  information. 


Format 

FUNCTIONEND  [exp] 
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FUNCTIONEXIT 

The  FUNCTIONEXIT  statement  is  a  synonym  for  the  EXIT  FUNCTION 
statement.  See  the  EXIT  statement  for  more  information. 


Format 

FUNCTIONEXIT  [exp] 
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GET 

The  GET  statement  moves  a  record  from  a  file  to  a  record  buffer  and 
makes  the  data  available  for  processing.  GET  statements  are  valid  on 
sequential,  relative,  indexed,  and  block  I/O  files. 

Format 

GET  i^chnl-exp  [ ,  position-clause  ] 

(  RFA  rfa-exp  1 

position-clause: 

s  RECORD  num-exp  / 

1  KEY#  key-clause  ) 

key-clause: 

int-expl  rel-op  key-exp 

(  EQ  ] 

rel-op: 

GE 

i  GT  J 

key-exp 

f  int-exp2  ) 

\  str-exp  ] 

Syntax  Rules 


ChnUexp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 


Statements  and  Functions  4-109 


GET 


Remarks 


1.  Position-clause 

•  Position-clause  specifies  the  position  of  a  record  in  a  file. 
BASIC-PLUS-2  signals  an  error  if  you  specify  a  position-clause  and 
chnl-exp  is  not  associated  with  a  disk  file.  If  you  do  not  specify 

a  position-clause,  GET  retrieves  records  sequentially.  Sequential 
record  access  is  valid  on  all  RMS  files. 

•  The  RFA  position-clause  allows  you  to  randomly  retrieve  records 
by  specifying  the  record  file  address  (RFA);  You  specify  the  disk 
address  of  a  record,  and  RMS  retrieves  the  record  at  that  address. 
All  file  organizations  can  be  accessed  by  RFA. 

Rfa-exp  in  the  RFA  position-clause  is  an  expression  of  the  RFA  data 
type  that  specifies  the  record's  file  address.  An  RFA  expression 
must  be  a  variable  of  the  RFA  data  type  or  the  GETRFA  function. 
Use  the  GETRFA  function  to  obtain  the  RFA  of  a  record. 

•  The  RECORD  position-clause  allows  you  to  randomly  retrieve 
records  in  relative  and  sequential  fixed  files  by  specifying  the 
record  number. 

—  Num-exp  in  the  RECORD  position-clause  specifies  the  number 
of  the  record  you  want  to  retrieve.  It  must  be  between  1  and 
the  number  of  the  record  with  the  highest  number  in  the  file. 

—  When  you  specify  a  RECORD  clause,  chnl-exp  must  be  a 
channel  associated  with  an  open  relative  or  sequential  fixed 
file. 

•  The  KEY  position-clause  allows  you  to  randomly  retrieve  records 
in  indexed  files  by  specifying  a  key  of  reference,  a  relational  test, 
or  a  key  value. 

2.  Key-clause 

•  In  a  key-clause,  int-expl  is  the  target  key  of  reference.  It  must 
be  an  integer  value  in  the  range  of  zero  through  the  highest- 
numbered  key  for  the  file.  The  primary  key  is  #0,  the  first  alter¬ 
nate  key  is  #1,  the  second  alternate  key  is  #2,  and  so  on.  Int-expl 
must  be  preceded  by  a  number  sign  ( # )  or  BASIC-PLUS-2  signals 
an  error. 

•  When  you  specify  a  key  clause,  chnl-exp  must  be  a  channel 
associated  with  an  open  indexed  file. 
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3.  Rel-op 

•  Rel-op  specifies  how  key-exp  is  to  be  compared  with  int-expl  in  the 
key-clause. 

—  EQ  means  equal  to 
—  GE  means  greater  than  or  equal  to 
—  GT  means  greater  than 

•  With  an  equal  to  (EQ)  key  match,  a  successful  GET  operation 
retrieves  the  first  record  in  the  file  that  equals  the  key  value 
specified  in  key-exp.  If  the  key  expression  is  a  str-exp  whose 
length  is  less  than  the  key  length,  characters  specified  by  the 
str-exp  are  matched  approximately  rather  than  exactly.  That  is,  if 
you  specify  a  string  expression  "ABC"  and  the  key  length  is  six 
characters,  BASIC-PLUS-2  matches  the  first  record  that  begins 
with  ABC.  If  you  specify  "ABCABC",  BASIC-PLUS-2  matches 
only  a  record  with  the  key  "ABCABC."  If  no  match  is  possible, 
BASIC-PLUS-2  signals  the  error  "Record  not  found"  (ERR=155). 

•  If  you  specify  a  greater  than  or  equal  to  (GE)  key  match,  a  success¬ 
ful  FIND  locates  the  first  record  that  equals  the  key  value  specified 
in  key-exp.  If  no  exact  match  is  possible,  BASIC-PLUS-2  selects 
the  next  record  in  the  key  sort  order  with  a  higher  key  value.  If 
no  such  record  exists,  BASIC-PLUS-2  signals  the  error  "Record  not 
found"  (ERR=155). 

•  If  you  specify  a  greater  than  (GT)  key  match,  a  successful  GET 
operation  retrieves  the  first  record  with  a  value  greater  than 
key-exp.  If  no  such  record  exists,  BASIC-PLUS-2  signals  the  error 
"Record  not  found"  (ERR=155). 

4.  Key-exp 

•  Int-expl  in  the  key  clause  specifies  an  integer  value  to  be  com¬ 
pared  with  the  key  value  of  a  record. 

•  Str-exp  in  the  key  clause  specifies  a  string  value  to  be  compared 
with  the  key  value  of  a  record.  The  string  expression  can  contain 
fewer  characters  than  the  key  of  the  record  you  want  to  retrieve 
but  it  cannot  be  a  null  string. 

5.  The  file  specified  by  chnl-exp  must  be  open  with  ACCESS  READ  or 
MODIFY  before  your  program  can  execute  a  GET  statement. 

6.  If  the  last  I/O  operation  was  a  successful  FIND  operation,  a  sequential 
GET  operation  retrieves  the  current  record  located  by  the  FIND 
operation  and  sets  the  next  record  pointer  to  the  record  logically 
succeeding  the  pointer. 
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7.  If  the  last  I/O  operation  was  not  a  FIND  operation,  a  sequential 
GET  operation  retrieves  the  next  record  and  sets  the  record  logically 
succeeding  the  record  pointer  to  the  current  record. 

•  For  sequential  files,  a  sequential  GET  operation  retrieves  the  next 
record  in  the  file. 

•  For  relative  files,  a  sequential  GET  operation  retrieves  the  record 
with  the  next  higher  cell  number. 

•  For  indexed  files,  a  sequential  GET  operation  retrieves  the  next 
record  in  the  current  key  of  reference. 

8.  A  successful  random  GET  operation  by  RFA  or  by  record  retrieves  the 
record  specified  by  rfa~exp  or  ini-exp, 

9.  A  successful  random  GET  operation  by  key  retrieves  the  first  record 
whose  key  satisfies  the  key-clause  comparison. 

10.  A  successful  random  GET  operation  by  RFA,  record,  or  key  sets  the 
value  of  the  current  record  pointer  to  the  record  }ust  read.  The  next 
record  pointer  is  set  to  the  next  logical  record. 

11.  An  unsuccessful  GET  operation  leaves  the  record  pointers  and  the 
record  buffer  in  an  undefined  state. 

12.  If  the  retrieved  record  is  smaller  than  the  receiving  buffer, 
BASIC-PLUS-2  fills  the  remaining  buffer  space  with  nulls. 

13.  If  the  retrieved  record  is  larger  than  the  receiving  buffer, 
BASIC-PLUS-2  truncates  the  record  and  signals  an  error. 

14.  You  should  not  use  a  GET  statement  on  a  terminal-format  or  virtual 
array  file. 

15.  When  you  access  a  shared  file,  a  successful  GET  locks  the  record  or 
bucket  and  unlocks  the  previously  locked  record  or  bucket. 

16.  A  successful  GET  operation  sets  the  value  of  the  RECOUNT  variable 
to  the  number  of  bytes  transferred  from  the  file  to  the  record  buffer. 
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Example 


10  DECLARE  LONG  rec-num 

MAP  (CUSREC)  WORD  cus.num  ^ 

STRING  cus.nain  *  20,  cus.add  *  20,  cus.clty  ■  10,  cus.zip  ■  9 
OPEN  "CUS.ACCT.DAT"  FOR  INPUT  AS  #1  ’  ” 

RELATIVE  FIXED,  ACCESS  MODIFY,  ft 

MAP  CUSREC 


INPUT  "Which  record  number  would  you  like  to  view" ;rec_num 

GET  #1,  RECORD  REC.NUM 

PRINT  "The  customer's  number  is  "; CUS.NUM 

PRINT  "The  customer's  name  is  ":cus.nam 

PRINT  "The  customer's  address  is  ";cus_add 

PRINT  "The  customer's  city  is  ";cus_city 

PRINT  "The  customer's  zip  code  is  ";cus.zip 

CLOSE  «1 

END 


V> 
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GETRFA 


The  GETRFA  function  returns  the  record's  file  address  (RFA)  of  the  last 
record  accessed  in  an  RMS  file  open  on  a  specified  channel. 


Format 

rfa-var  =  GflWk(chnl-exp} 


Syntax  Rules 


1.  Rfa-var  is  a  variable  of  the  RFA  data  type. 

2.  Chnl-exp  is  the  channel  number  of  an  open  RMS  file.  You  cannot 
precede  the  chnl-exp  with  a  number  sign  (#). 

3.  You  must  access  a  record  in  the  file  with  a  GET,  FIND,  or  PUT 
statement  before  using  the  GETRFA  function,  or  BASIC-PLUS-2 
signals  "No  current  record"  (ERR=131). 


Remarks 

1.  There  must  be  a  file  open  on  the  specified  chnl-exp  or  BASIC-PLUS-2 
signals  an  error. 

2.  You  can  use  the  GETRFA  function  with  RMS  sequential,  relative, 
indexed,  and  (except  on  RSTS/E  systems)  block  I/O  files. 

3.  The  RFA  value  returned  by  the  GETRFA  function  can  be  used  only 
for  assignments  to  and  comparisons  with  other  variables  of  the  RFA 
data  t)q)e.  Comparisons  are  limited  to  equal  to  (=)  and  not  equal  to 
(  <  >  )  relational  operations. 

4.  RFA  values  cannot  be  printed  or  used  for  any  arithmetic  operations. 
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Example 


10  DECLARE  RFA  R_ARRAY(1  TO  100) 


FOR  IX  -  IX  TO  lOOX 
PUT  #1 

R_ARRAY(IX)  •  GETRFA(l) 
NEXT  IX 
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GOSUB 


The  GOSUB  statement  transfers  control  to  a  specified  line  number  or  label 
and  stores  the  location  of  the  GOSUB  statement  for  eventual  return  from 
the  subroutine. 


Format 


target 


Syntax  Rules 


1.  Target  must  refer  to  an  existing  line  number  or  label  in  the  same 
program  unit  as  the  GOSUB  statement  or  BASlC-PLUS-2  signals  an 
error. 

2.  Target  cannot  be  inside  a  block  structure  such  as  a  FOR  . .  .  NEXT, 
WHILE,  or  UNTIL  loop  or  a  multi-line  function  definition  unless  the 
GOSUB  statement  is  also  within  that  block  or  function  definition. 


Remarks 


None. 
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Example 


10  GOSUB  subroutine.! 


200  subrout ine.l : 


RETURN 
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GOTO 


The  GOTO  statement  transfers  control  to  a  specified  line  number  or  label. 


Format 


{ 


GOTO  \ 
GOTO  j 


target 


Syntax  Rules 


1.  Target  must  refer  to  an  existing  line  number  or  label  in  the  same 
program  unit  as  the*  GOTO  statement  or  BASIC-PLUS-2  signals  an 
error. 

2.  Target  cannot  be  inside  a  block  structure  such  as  a  FOR  . .  .  NEXT, 
WHILE,  or  UNTIL  loop  or  a  multi-line  function  definition  unless  the 
GOTO  statement  is  also  inside  that  loop  or  function  definition. 


Remarks 

None. 


Example 


10  IF  answer  »  0 

THEN  GOTO  done 
END  IF 


done: 

EXIT  PROGRAM 
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The  IF  statement  evaluates  a  conditional  expression  and  transfers  program 
control  depending  on  the  resulting  value. 


Format 

Conditional 

IF  cond-exp  THEN  statement . . .  [  ELSE  statement ...  7 

END  IF 

Statement  Modifier 

Statement  IF  cond-exp 


Syntax  Rules 


1.  Conditional 

•  Cond-exp  can  be  any  valid  conditional  expression. 

•  All  statements  between  the  THEN  keyword  and  the  next  ELSE, 
line  number,  or  END  IF  are  part  of  the  THEN  clause.  All  state¬ 
ments  between  the  keyword  ELSE  and  the  next  line  number  or 
END  IF  are  part  of  the  ELSE  clause. 

•  BASIC-PLUS-2  assumes  a  GOTO  statement  when  the  keyword 
ELSE  is  followed  by  a  line  number.  When  the  target  of  a, GOTO 
statement  is  a  label,  the  keyword  GOTO  is  required.  The  use  of 
this  syntax  is  not  recommended  for  new  program  development. 

•  The  END  IF  statement  terminates  the  most  recent  unterminated  IF 
statement. 

•  A  new  line  number  terminates  all  unterminated  IF  statements. 
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2.  Statement  Modifier 

•  IF  can  modify  any  executable  statement  except  a  block  statement 
.  such  as  FOR,  WHILE,  UNTIL,  or  SELECT. 

•  Cond-exp  can  be  any  valid  conditional  expression. 


Remarks 


1.  Conditional 

•  BASIC-PLUS-2  evaluates  the  conditional  expression  for  truth 
or  falsity.  If  true  (nonzero),  BASIC-PLUS-2  executes  the  THEN 
clause.  If  false  (zero),  BASIC-PLUS-2  skips  the  THEN  clause  and 
executes  the  ELSE  clause,  if  present. 

•  The  keyword  NEXT  cannot  be  in  a  THEN  or  ELSE  clause  unless 
the  FOR  or  WHILE  statement  associated  with  the  keyword  NEXT 
is  also  part  of  the  THEN  or  ELSE  clause. 

•  If  a  THEN  or  ELSE  clause  contains  a  block  statement  such  as  a 
FOR,  SELECT,  UNTIL,  or  WHILE,  then  a  corresponding  block 
termination  statement  such  as  a  NEXT  or  END  must  appear  in  the 
same  THEN  or  ELSE  clause. 

•  IF  statements  can  be  nested  to  12  levels.  ^ 

•  Any  executable  statement  is  valid  in  the  THEN  or  ELSE  clause, 
including  another  IF  statement.  You  can  include  any  number  of 
statements  in  either  clause. 

•  Execution  continues  either  at  the  statement  following  the  END  IF 
clause  or  at  the  first  line  number  following  an  unterminated  IF 
statement. 


2.  Statement  Modifier 

BASIC-PLUS-2  executes  the  statement  only  if  the  conditional  expres¬ 
sion  is  true  (nonzero). 
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Example 

10  IF  Update.llag  *  True 

THEN 

Weekly.salary  >  New.rate  *  40.0 

UPDATE  #1 

IF  Dept  <>  New.dept 

THEN 

GET  «1.  KEY  «1  EQ  New.dept 

Dept.employeee  «  Dept.employees  *  1 

UPDATE  #1 

END  IF 

PRINT  "Update  complete" 

ELSE 

PRINT  "Skipping  update  for  this  employee" 

END  IF 
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Syntax  Rules 

1. 

2. 

3. 

4. 

5. 

6. 


INPUT  statement  assigns  values  from  your  terminal  or  from  a 
inal-format  file  to  program  variables. 


Format 


INPUT  [  #chnl-exp,  ]  input-item  [  \  [  \  input-item  ]  . . . 


input-item:  [  strng-const  \  [  \  ]  str-var 


Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 

Str-const  is  the  prompt  issued  for  the  input  string  value. 

Str-var  is  a  program  variable  to  which  the  input  string  value  is 
assigned. 

You  can  include  more  than  one  input-item  in  an  INPUT  statement  by 
separating  them  with  commas  (,)  or  semicolons  (;). 

The  comma  or  semicolon  that  follows  str-var  has  no  formatting  effect. 
BASIC-PLUS-2  always  advances  to  a  new  line  when  you  terminate 
input  with  a  carriage  return. 

The  separator  that  directly  follows  str-const  determines  where  the 
question  mark  prompt  (if  requested)  is  displayed  and  where  the  cursor 
is  positioned  for  input. 

•  A  comma  causes  BASIC-PLUS-2  to  skip  to  the  next  print  zone  and 
display  the  question  mark  unless  a  SET  NO  PROMPT  statement 
has  been  executed.  For  example: 


Syntax  Rules 

1. 

2. 

3. 

4. 

5. 

6. 
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DECLARE  STRING  your .name 

INPUT  "What  is  your  name"  ,your_naine 

Output 

What  Is  your  name  ? 

•  A  semicolon  causes  BASIC-PLUS-2  to  display  the  question  mark 
next  to  str<on$t  unless  a  SET  NO  PROMPT  statement  has  been 
executed.  For  example: 

DECLARE  STRING  your.name 

INPUT  "What  is  your  name" ; your .name 

Output 

What  is  your  name? 

7.  BASIC-PLUS-2  always  advances  to  a  new  line  when  you  terminate 
input  with  a  carriage  return. 


Remarks 


1.  If  you  do  not  specify  a  channel,  the  default  chnUexp  is  #0  (the  con¬ 
trolling  terminal).  If  a  chnUexp  is  specified,  a  file  must  be  open  on  that 
channel  with  ACCESS  READ  or  MODIFY  before  the  INPUT  statement 
can  execute. 

2.  If  input  comes  from  a  terminal,  BASIC-PLUS-2  displays  str-const,  if 
present.  If  the  terminal  is  open  on  channel  #0,  BASIC-PLUS-2  also 
displays  a  question  mark  ( ? ). 

3.  You  can  disable  the  question  mark  prompt  by  using  the  SET  NO 
PROMPT  statement.  See  the  SET  PROMPT  statement  for  more 
information. 

4.  When  BASIC-PLUS-2  receives  a  line  terminator  or  a  complete  record, 
it  checks  each  data  element  for  correct  data  type  and  range  limits,  then 
assigns  the  values  to  the  corresponding  variables. 

5.  If  you  specify  a  string  variable  to  receive  the  input  text,  and  the  user 
enters  an  unquoted  string  in  response  to  the  prompt,  BASIC-PLUS-2 
ignores  the  string's  leading  and  trailing  spaces  and  tabs.  An  unquoted 
string  cannot  contain  any  commas. 
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6.  If  there  is  not  enough  data  in  the  current  record  or  line  to  satisfy  the 
variable  list,  BASIC-PLUS-2  takes  one  of  the  following  actions: 

•  If  the  input  device  is  a  terminal  and  you  have  not  specified  SET 
NO  PROMPT,  BASIC-PLUS-2  repeats  the  question  mark  but  not 
the  sir-const  on  a  new  line  until  sufficient  data  is  entered. 

•  If  the  input  device  is  not  a  terminal,  BASIC-PLUS-2  signals  the 
error  "Not  enough  data  in  record"  (ERR=59). 

7.  If  there  are  more  data  items  than  variables  in  the  INPUT  response, 
BASIC-PLUS-2  ignores  the  excess. 

8.  If  there  is  an  error  while  data  is  being  converted  or  assigned  (for 
example,  string  data  being  assigned  to  a  numeric  variable), 
BASIC-PLUS-2  takes  one  of  the  following  actions: 

•  If  there  is  no  error  handler  in  effect  and  the  input  device  is  a 
terminal,  BASIC-PLUS-2  signals  a  warning,  reexecutes  the  INPUT 
statement,  and  displays  sir-const  and  the  input  prompt. 

•  If  there  is  an  error  handler  in  effect  and  the  input  device  is  not 
a  terminal,  BASIC-PLUS-2  signals  the  error  "Illegal  number" 
(ERR=52)  or  "Data  format  error"  (ERR=50). 

9.  When  a  RESUME  statement  transfers  control  to  an  INPUT  statement, 
the  INPUT  statement  retrieves  a  new  record  or  line  regardless  of  any 
data  left  in  the  previous  record  or  line. 

10.  After  a  successful  INPUT  statement,  the  RECOUNT  variable  contains 
the  number  of  characters  transferred  from  the  file  or  terminal  to  the 
record  buffer. 

11.  If  you  terminate  input  text  with  CTRL/Z,  BASIC-PLUS-2  assigns  the 
value  to  the  variable  and  signals  the  error  "End  of  file  on  device" 
(ERR=11)  when  the  next  terminal  input  statement  executes.  If  you 
are  in  the  BASIC  environment  and  there  is  no  subsequent  INPUT, 
INPUT  LINE,  or  LINPUT  statement  in  the  program,  the  CTRL/Z  is 
passed  to  BASIC-PLUS-2  as  a  signal  to  exit  the  BASIC  environment. 
BASIC-PLUS-2  signals  the  error  "Unsaved  changes  have  been  made, 
CTRL/Z  or  EXIT  to  exit"  if  you  have  made  changes  to  your  program 
or  are  running  a  program  that  has  never  been  saved.  If  you  have  not 
made  changes,  BASIC-PLUS-2  exits  from  the  BASIC  environment  and 
does  not  signal  an  error. 
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Example 


10  DECLARE  STRING  var.l.  k 
INTEGER  var.2 

INPUT  "The  first  variable" ;var_l,  "The  second  variable" ;var_2 

Output 

The  first  variable?  name 
The  second  variable?  4 
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INPUT  LINE 

The  INPUT  LINE  statement  assigns  a  string  value,  including  the  line 
terminator,  from  a  terminal  or  terminal-format  file  to  a  string  variable. 


Format 


INPUT  LINE  [  #chnl-exp,  ]  input-item  /^  |  !  |  input-item  ] 
input-item:  [  strng-const  |  !  | ./  str-var 


Syntax  Rules 


1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 

2.  Str-const  is  the  prompt  issued  for  the  input  string  value. 

3.  Str-var  is  a  program  variable  to  which  the  input  string  value  is  as¬ 
signed. 

4.  You  can  include  more  than  one  input-item  in  an  INPUT  LINE  state¬ 
ment  by  separating  them  with  commas  ( , )  or  semicolons  ( ; ). 

5.  The  separator  (comma  or  semicolon)  that  directly  follows  str-var  has 
no  formatting  effect.  BASIC-PLUS-2  always  advances  to  a  new  line 
when  you  terminate  input  with  a  carriage  return. 

6.  The  separator  that  directly  follows  str-const  determines  where  the 
question  mark  (if  requested)  is  displayed  and  where  the  cursor  is 
positioned  for  input. 

•  A  comma  causes  BASIC-PLUS-2  to  skip  to  the  next  print  zone  and 
display  the  question  mark  unless  a  SET  NO  PROMPT  statement 
has  been  executed.  For  example: 
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10  DECLARE  STRING  your.name 
INPUT  LINE  "Name" ,your_name 

Output 

Name  ? 

•  A  semicolon  causes  BASIC-PLUS-2  to  display  the  question  mark 
next  to  str-const  unless  a  SET  NO  PROMPT  statement  has  been 
executed.  For  example: 

10  DECLARE  STRING  your.name 
INPUT  LINE  "Name" ;your_name 

Output 

Name? 

7.  BASIC-PLUS-2  always  advances  to  a  new  line  when  you  terminate 
input  with  a  carriage  return. 


Remarks 


1.  The  default  chnl-exp  is  #0  (the  controlling  terminal).  If  a  channel  is 
specified,  a  file  must  be  open  on  that  channel  with  ACCESS  READ  or 
ACCESS  MODIFY  before  the  INPUT  LINE  statement  can  execute. 

2.  BASIC-PLUS-2  signals  an  error  if  the  INPUT  LINE  statement  has  no 
argument. 

3.  If  input  comes  from  a  terminal,  BASIC-PLUS-2  displays  the  contents 
of  str-constl,  if  present.  If  the  terminal  is  open  on  channel  #0, 
BASIC-PLUS-2  also  displays  a  question  mark  (?). 

4.  You  can  disable  the  question  mark  prompt  by  using  the 

SET  NO  PROMPT  statement.  See  the  SET  PROMPT  statement  for 
more  information. 

5.  The  INPUT  LINE  statement  assigns  all  input  characters,  including 
any  line  terminator,  to  string  variables.  Single  and  double  quotation 
marks,  coinmas,  tabs,  leading  and  trailing  spaces,  and  other  special 
characters  in  the  string  are  part  of  the  data. 

6.  When  a  RESUME  statement  transfers  control  to  an  INPUT  LINE 
statement,  the  INPUT  LINE  statement  retrieves  a  new  record  or  line 
regardless  of  any  data  left  in  the  previous  record  or  line. 
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Example 


7.  After  a  successful  INPUT  LINE  statement,  the  RECOUNT  variable 
contains  the  number  of  characters  transferred  from  the  file  or  terminal 
to  the  record  buffer. 

8.  If  you  terminate  input  text  with  CTRL/Z,  BASIC-PLUS-2  assi^s^the 
value  to  the  variable  and  signals  the  error  "End  of  file  on  device" 
(ERR=11)  when  the  next  terminal  input  statement  executes.  If  you  are 
in  the  BASIC  environment  and  there  is  no  next  INPUT,  INPUT  LINE, 
or  LINPUT  statement  in  the  program,  the  CTRL/Z  is  passed  to 
BASIC-PLUS-2  as  a  signal  to  exit  the  BASIC  environment. 
BASIC-PLUS-2  signals  the  error  "Unsaved  changes  have  been  made, 
CTRL/Z  or  EXIT  to  exit'  if  you  have  made  changes  to  your  program. 
If  you  have  not  made  changes,  BASIC-PLUS-2  exits  from  the  BASIC 
environment  and  does  not  signal  an  error. 


10  DECLARE  STRING  Z , N , record.strlng 

INPUT  LINE  "Type  two  words",  ZS.'Type  your  name';N$ 
INPUT  LINE  #4%.  record_8tring$ 
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liySTR 

The  INSTR  function  searches  for  a  substring  within  a  string.  It  returns  the 
position  of  the  substring's  starting  character. 

Format 

int-var  =  \NSlf{(int-exp,  str-expl,  str-exp2) 

Syntax  Rules 

1.  Int-exp  specifies  the  character  position  in  the  main  string  at  which 
BASIC-PLUS-2  starts  the  search. 

2.  Str-expl  specifies  the  main  string. 

3.  Str-exp2  specifies  the  substring. 


Remarks 


1.  The  position  returned  by  the  INSTR  function  is  the  number  of  charac¬ 
ters  from  the  beginning  of  the  string  regardless  of  the  value  specified 
in  int-exp. 

2.  If  int-exp  is  less  than  1,  INSTR  starts  its  search  at  the  first  character  of 
the  string. 

3.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 

4.  The  INSTR  function  searches  str-expl,  the  main  string,  for  the  first 
occurrence  of  a  substring,  str-exp2,  and  returns  the  position  of  the 
substring's  first  character. 

5.  If  you  know  that  the  substring  is  not  near  the  beginning  of  the  string, 
specifying  a  starting  position  greater  than  1  speeds  program  execution 
by  reducing  the  number  of  characters  BASIC-PLUS-2  must  search. 
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6.  INSTR  returns  the  character  position  in  the  main  string  at  which 

BASIC-PLUS-2  finds  the  substring,  except  in  the  following  situations: 

•  If  only  the  substring  is  null,  and  if  int-exp  is  less  than  or  equal  to 
zero,  INSTR  returns  a  value  of  1. 

•  If  only  the  substring  is  null,  and  if  int-exp  is  equal  to  or  greater 
than  1  and  less  than  or  equal  to  the  length  of  the  main  string, 
INSTR  returns  the  value  of  int-exp. 

•  If  only  the  substring  is  null,  and  if  int-exp  is  greater  than  the 
length  of  the  main  string,  INSTR  returns  the  main  string's  length 
plus  1. 

•  If  the  substring  is  not  null,  and  if  int-exp  is  greater  than  the  length 
of  the  main  string,  INSTR  returns  a  value  of  zero. 

•  If  only  the  main  string  is  null,  INSTR  returns  a  value  of  zero. 

•  If  both  the  main  string  and  the  substring  are  null,  INSTR  returns 
a  1. 

7.  If  BASIC-PLUS-2  cannot  find  the  substring,  INSTR  returns  a  value  of 

zero. 


Example 


10  DECLARE  STRING  alpha,  k 
INTEGER  result 
alpha  *  "ABCDEF" 
result  -  INSTRd, alpha. "DEF") 
PRINT  result 

Output 
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iniT 

The  INT  function  returns  the  floating-point  value  of  the  largest  whole 
number  less  than  or  equal  to  a  specified  expression. 


Format 

real-var  =  INT  (real-exp) 


Syntax  Rules 

None. 


Remarks 

1.  If  real-exp  is  negative,  BASIC-PLUS-2  returns  the  largest  whole 
number  less  than  or  equal  to  real-exp.  For  example,  INT(-5.3)  is  -6. 

2.  BASIC-PLUS-2  expects  the  argument  of  the  INT  function  to  be  a  real 
expression.  When  the  argument  is  a  real  expression,  BASIC-PLUS-2 
returns  a  value  of  the  same  floating-point  size.  When  the  argument 
is  not  a  real  expression,  BASIC-PLUS-2  converts  the  argument  to 
the  default  floating-point  size  and  returns  a  value  of  the  default 
floating-point  size. 
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Examples 


Example  1 

10  DECLARE  SINGLE  any.num,  result 
any.num  ■  6.667 
result  *  INT (any.num) 

PRINT  result 

Output  1 


Example  2 

10  IThls  example  contrasts  the  INT  and  FIX  functions 
DECLARE  SINGLE  test.num 
test.num  ■  -32.7 

PRINT  "INT  OF  -32.7  IS:  INT(test.num) 

PRINT  "FIX  OF  -32.7  IS:  ";  FlX(test.num) 

Output  2 

INT  OF  -32.7  IS:  -33 
FIX  OF  -32.7  IS:  -32 
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The  INTEGER  function  converts  a  numeric  expression  or  numeric  string  to 
a  specified  or  default  INTEGER  data  type. 


Format 


int-var  =  \H\iGif{(exp 


,BYTE 
.WORD 
.  .LONG 


I 


Syntax  Rules 

Exp  can  be  either  numeric  or  string.  A  string  expression  can  contain  the 
ASCII  digits  0  through  9,  a  plus  sign  (+),  or  a  minus  sign  (-). 


Remarks 


1.  BASIC-PLUS-2  evaluates  exp,  then  converts  it  to  the  specified 
INTEGER  size.  If  you  do  not  specify  a  size,  BASIC-PLUS-2  uses 
the  default  INTEGER  size. 

2.  If  exp  is  a  string,  BASIC-PLUS-2  ignores  leading  and  trailing  spaces 
and  tabs. 

3.  The  INTEGER  function  returns  a  value  of  zero  when  a  string  argument 
contains  only  spaces  and  tabs,  or  when  it  is  null. 
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Example 


10  INPUT  "Enter  a  floating-point  number" ;F_P 
PRINT  INTEGER(F_P.  WORD) 

Output 

Enter  a  floating-point  number?  76.99 
76 
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ITERATE 


The  ITERATE  statement  allows  you  to  explicitly  reexecute  a  loop. 


Format 

ITERATE  [label] 

Syntax  Rules 


Label  is  the  name  that  identifies  the  FOR  .  .  .  NEXT,  WHILE,  or  UNTIL 
loop.  For  more  information  on  labels,  see  Section  1.1.2. 


Remarks 


1.  ITERATE  is  equivalent  to  an  unconditional  branch  to  the  current  loop's 
NEXT  statement.  If  you  supply  a  label,  ITERATE  transfers  control  to 
the  NEXT  statement  in  the  specified  loop.  If  you  do  not  supply  a 
label,  ITERATE  transfers  control  to  the  current  loop's  NEXT  statement. 

2.  The  ITERATE  statement  can  be  used  only  within  a  FOR  . . .  NEXT, 
WHILE,  or  UNTIL  loop. 


Example 


10  Date.loop : 


WHILE  n  «  1% 

GET  #1 

ITERATE  Date.loop  IF  Day$  <>  Today! 

ITERATE  Date.loop  IF  Month!  <>  Thle.month! 
ITERATE  Date.loop  IF  Year!  <>  Thle.year! 
PRINT  Item! 

NEXT 
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KILL 


The  KILL  statement  deletes  a  disk  file,  removes  the  file's  directory  entry, 
and  releases  the  file's  storage  space. 


Format 

KILL  file-spec 

Syntax  Rules 

File-spec  can  be  a  quoted  string  constant,  a  string  variable,  or  a  string 
expression.  It  cannot  be  an  unquoted  string  constant. 


Remarks 


1.  The  KILL  statement  marks  a  file  for  deletion  but  does  not  delete  the 
file  until  all  users  have  closed  it. 

2.  If  you  do  not  specify  a  complete  file  specification,  BASIC-PLUS-2  uses 
the  default  device  and  directory.  If  you  do  not  specify  a  file  version, 
BASIC-PLUS-2  on  RSX  systems  deletes  the  highest  version  of  the  file. 

3.  The  file  must  exist,  or  BASIC-PLUS-2  signals  an  error. 

4.  You  can  delete  a  file  in  another  directory  if  you  have  access  to  that 
directory  and  privilege  to  delete  the  file. 


Example 


10  KILL  "TEMP.DAT" 
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LEFT$ 


The  LEFT$  function  extracts  a  specified  substring  from  a  string's  left  side, 
leaving  the  main  string  unchanged. 


Format 

str-var  =  LEFT[$]  (str-exp,  int-exp)) 


Syntax  Rules 


1.  Int-exp  specifies  the  number  of  characters  to  be  extracted  from  the  left 
side  of  str-exp. 

2.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 


Remarks 


1.  The  LEFTS  function  extracts  a  substring  from  the  left  of  the  specified 
str-exp  and  stores  it  in  str-var, 

2.  If  int-exp  is  less  than  1,  LEFTS  returns  a  null  string. 

3.  If  int-exp  is  greater  than  the  length  of  str-exp,  LEFTS  returns  the  entire 
string. 
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Example 


10  DECLARE  STRING  sub.strlng,  maln.string 
main.strlng  «  "1234567" 
sub.string  *  LEFT$(main_8tring,  4) 
PRINT  sub.string 

Output 

1234 
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LERI 


The  LEN  function  returns  an  integer  value  equal  to  the  number  of  charac¬ 
ters  in  a  specified  string. 


Format 

int-var  =  LiN(str-exp) 


Syntax  Rules 

None. 


Remarks 


1.  If  str-exp  is  null,  LEN  returns  a  value  of  zero. 

2.  The  length  of  str-exp  includes  leading,  trailing,  and  embedded  blanks. 
Tabs  in  str-exp  are  treated  as  a  single  space. 

3.  The  value  returned  by  the  LEN  function  is  a  WORD  integer. 


Example 


10  DECLARE  STRING  alpha,  k 
INTEGER  length 
alpha  *  "ABCDEFG" 
length  «  LEN (alpha) 
PRINT  length 

Output 
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LET 


The  LET  statement  assigns  a  value  to  one  or  more  variables. 


Format 

[LET]  var,  . . .  =  exp 

Syntax  Rules 

The  keyword  LET  is  optional. 

Remarks 


1.  You  cannot  assign  string  data  to  a  numeric  variable  or  unquoted 
numeric  data  to  a  string  variable. 

2.  The  value  assigned  to  a  numeric  variable  is  converted  to  the  variable's 
data  type.  For  example,  if  you  assign  a  floating-point  value  to  an 
integer  variable,  BASIC-PLUS-2  truncates  the  value  to  an  integer. 

3.  For  dynamic  strings,  the  destination  string's  length  equals  the  source 
string's  length. 

4.  When  you  assign  a  value  to  a  fixed-length  string  variable  (a  variable 
declared  in  a  COMMON  or  MAP  statement),  the  value  is  left-justified 
and  padded  with  spaces  or  truncated  to  match  the  length  of  the  string 
variable.  Because  of  this  padding,  the  length  of  the  string  is  always 
the  length  declared  in  the  COMMON  or  MAP  statement.  You  cannot 
easily  concatenate  these  strings  because  of  the  padding. 

5.  To  add  characters  to  a  static  string,  you  must  first  strip  off  the  trailing 
blanks  with  the  TRM$  function.  For  example: 

100  COMMON  At  •  16 
At  -  *A" 

PRINT  At 
At  >  At  +  "B" 

PRINT  At 

At  -  TRMttAt)  +  "B" 

PRINT  At 
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Output 

A 

A 

AB 


6.  Virtual  array  strings  are  of  fixed  length  as  declared  in  the  DIMENSION 
statement.  When  you  assign  a  value  to  a  virtual  array  string,  it  is  left- 
justified  and  padded  with  null  characters.  Therefore,  values  stored  in 
virtual  arrays  cannot  contain  trailing  null  characters. 


Example 


10  DECLARE  STRING  alpha.  A 
INTEGER  length 
LET  alpha  *  "ABCDEFG" 
LET  length  >  LEN (alpha) 
PRINT  length 

Output 
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LiniPUT 


The  LINPUT  statement  assigns  a  string  value,  without  line  terminators, 
from  a  terminal  or  terminal-format  file  to  a  string  variable. 


Format 

LINPUT  [  #chnl-exp,  ]  input-item  /^  |  !  |  input-item  ] 
input-item:  [  strng-const  |  !  |  ^  sfr-rar 


Syntax  Rules 

1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 

2.  Str-const  is  the  prompt  issued  for  the  input  value. 

3.  Str-var  is  a  program  string  variable  to  which  the  input  value  is  as¬ 
signed. 

4.  You  can  include  more  than  one  input-item  in  an  LINPUT  statement  by 
separating  them  with  commas  ( , )  or  semicolons  ( ; ). 

5.  The  separator  (comma  or  semicolon)  that  directly  follows  str-var  has 
no  formatting  effect.  BASIC-PLUS-2  always  advances  to  a  new  line 
when  you  temunate  input  with  a  carriage  return. 

6.  The  separator  character  that  directly  follows  str-const  determines 
where  the  question  mark  (if  requested)  is  displayed  and  where  the 
cursor  is  positioned  for  input. 
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•  A  comma  causes  BASIC-PLUS-2  to  skip  to  the  next  print  zone  to 
display  the  question  mark  unless  a  SET  NO  PROMPT  statement 
has  been  executed.  For  example: 

10  DECLARE  STRING  your_name 
LINPUT  "Name" ,your_name 

Output 

Name  ? 

•  A  semicolon  causes  BASIC-PLUS-2  to  display  the  question  mark 
next  to  str-const  unless  a  SET  NO  PROMPT  statement  has  been 
executed.  For  example: 

10  DECLARE  STRING  your.name 

LINPUT  "What  is  your  name" ; your.name 

Output 

What  is  your  name? 

7.  BASIC-PLUS-2  always  advances  to  a  new  line  when  you  terminate 
input  with  a  carriage  return. 


Remarks 


1.  The  default  chnl-exp  is  #0  (the  controlling  terminal).  If  you  specify  a 
channel,  the  file  associated  with  that  channel  must  have  been  opened 
with  ACCESS  READ  or  MODIFY. 

2.  BASIC-PLUS-2  signals  an  error  if  the  LINPUT  statement  has  no 
argument. 

3.  If  input  comes  from  a  terminal,  BASIC-PLUS-2  displays  the  contents 
of  str-constl,  if  present.  If  the  terminal  is  open  on  channel  #0, 
BASIC-PLUS-2  also  displays  a  question  mark  ( ? ). 

4.  You  can  disable  the  question  mark  prompt  by  using  the 

SET  NO  PROMPT  statement.  See  the  SET  PROMPT  statement  for 
more  information. 

5.  The  LINPUT  statement  assigns  all  characters,  except  a  line  terminator, 
to  str-varl.  Single  and  double  quotation  marks,  commas,  tabs,  leading 
and  trailing  spaces,  or  other  special  characters  in  the  string  are  part  of 
the  data. 
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6.  If  a  RESUME  statement  transfers  control  to  a  LINPUT  statement,  the 
LINPUT  statement  retrieves  a  new  record  regardless  of  any  data  left  in 
the  previous  record. 

7.  After  a  successful  LINPUT  statement,  the  RECOUNT  variable  contains 
the  number  of  bytes  transferred  from  the  file  or  terminal  to  the  record 
buffer. 

8.  If  you  terminate  input  text  with  CTRL/Z,  BASIC-PLUS-2  assies  the 
value  to  the  variable  and  signals  the  error  "End  of  file  on  device" 
(ERR=11)  when  the  next  terminal  input  statement  executes.  If  you 
are  in  the  BASIC  environment  and  there  is  no  next  INPUT,  INPUT 
LINE,  or  LINPUT  statement  in  the  program,  the  CTRL/Z  is  passed  to 
BASIC-PLUS-2  as  a  signal  to  exit  the  BASIC  environment. 


Example 


10  DECLARE  STRING  last .name 

LINPUT  "ENTER  YOUR  LAST  NAME" ; Last .name 
LINPUT  #2%.  Last .name 
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The  LOG  function  returns  the  natural  logarithm  (base  e)  of  a  specified 
number.  The  LOG  function  is  the  inverse  of  the  EXP  function. 


Format 

reaf-i/ar  =  LOG  frea/-expj 

Syntax  Rules 

None. 


Remarks 


1.  Real-exp  must  be  ^eater  than  zero.  An  attempt  to  find  the  logarithm 
of  zero  or  a  negative  number  causes  BASIC-PLUS-2  to  signal  "Illegal 
argument  in  LOG"  (ERR=53). 

2.  The  LOG  function  uses  the  mathematical  constant  c  as  a  base. 
BASIC-PLUS-2  approximates  e  to  be  2.718281828459045  (double 
precision). 

3.  The  LOG  function  returns  the  exponent  to  which  e  must  be  raised  to 
equal  real-exp. 

4.  BASIC-PLUS-2  expects  the  argument  of  the  LOG  function  to  be  a  real 
expression.  When  the  argument  is  a  real  expression,  BASIC-PLUS-2 
returns  a  value  of  the  same  floating-point  size.  When  the  argument 
is  not  a  real  expression,  BASIC-PLUS-2  converts  the  argument  to 
the  default  floating-point  size  and  returns  a  value  of  the  default 
floating-point  size. 
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Example 


10  DECLARE  SINGLE  exponent 
exponent  ^  LOG (98. 6) 
PRINT  exponent 

Output 

4.59107 
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LOG10 


The  LOG  10  function  returns  the  common  logarithm  (base  10)  of  a  speci¬ 
fied  number. 


Format 

real-var  =  LOG  1 0  (real-exp} 

Syntax  Rules 

None. 

Remarks 

1.  Real-exp  must  be  larger  than  zero.  An  attempt  to  find  the  logarithm 
of  zero  or  a  negative  number  causes  BASIC-PLUS-2  to  signal  "Illegal 
argument  in  LOG"  (ERR=53). 

2.  The  LOG  10  function  returns  the  exponent  to  which  10  must  be  raised 
to  equal  real-exp. 

3.  BASIC-PLUS-2  expects  the  argument  of  the  LOGIO  function  to  be  a 
real  expression.  When  the  argument  is  a  real  expression, 
BASIC-PLUS-2  returns  a  value  of  the  same  floating-point  size.  When 
the  argument  is  not  a  real  expression,  BASIC-PLUS-2  converts  the 
argument  to  the  default  floating-point  size  and  returns  a  value  of  the 
default  floating-point  size. 
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Example 


10  DECLARE  SINGLE  exp.base.lO 
exp.base.lO  *  LOG10(250) 
PRINT  exp.base.lO 

Output 

2.39794 
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LSET 


The  LSET  statement  assigns  left-justified  data  to  a  string  variable.  LSET 
does  not  change  the  length  of  the  destination  string  variable. 


Format 

LSET  str-var,  . . .  =  str-exp 


Syntax  Rules 

Str-var  is  the  destination  string.  Str-exp  is  the  string  value  assigned  to 
str-var. 


Remarks 


1.  The  LSET  statement  treats  all  strings  as  fixed  length.  LSET  does  not 
change  the  length  of  the  destination  string  or  create  new  storage. 
LSET  does,  however,  overwrite  the  current  storage  of  str-var, 

2.  If  the  destination  string  is  longer  than  str-exp,  LSET  left-justifies 
str-exp  and  pads  it  with  spaces  on  the  right.  If  smaller,  LSET  truncates 
characters  from  the  right  of  str-exp  to  match  the  length  of  str-var. 

3.  With  string  virtual  arrays,  LSET  changes  the  length  of  str-exp  to  the 
declared  length  by  padding  it  with  spaces  on  the  right.  Note  that  the 
LET  statement  uses  null  characters  for  padding. 
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Example 


10  DECLARE  STRING  alpha 
alpha  *  "ABODE" 

LSET  alpha  «  "FGHIJKLMN" 
PRINT  alpha 

Output 

FGHIJ 
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MAG 


The  MAG  function  returns  the  absolute  value  of  a  specified  expression. 
The  returned  value  has  the  same  data  type  as  that  of  the  expression. 


Format 

var  =  MKQfexp) 


Syntax  Rules 

None. 


Remarks 


1.  The  returned  value  is  always  greater  than  or  equal  to  zero.  The 
absolute  value  of  zero  is  zero.  The  absolute  value  of  a  positive 
number  equals  that  number.  The  absolute  value  of  a  negative  number 
equals  that  number  multiplied  by  -1. 

2.  The  MAG  function  is  similar  to  the  ABS  function  in  that  it  returns 
the  absolute  value  of  a  number.  The  ABS  function,  however,  takes  a 
floating-point  argument  and  returns  a  floating-point  value.  The  MAG 
function  takes  an  argument  of  any  numeric  data  type  and  returns  a 
value  of  the  same  data  type  as  the  argument.  It  is  recommended  that 
you  use  the  MAG  function  rather  than  the  ABS  and  ABS%  functions, 
because  the  MAG  function  returns  a  value  using  the  data  type  of  the 
argument. 


Statements  and  Functions  4-151 


MAG 


Example 


10  DECLARE  SINGLE  A 
A  -  -34.6 
PRINT  MAG (A) 

Output 

34.6 
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MAGTAPE 


The  MAGTAPE  function  permits  your  program  to  control  unformatted 
magnetic  tape  files. 


Format 

int-varl  =  MAQJAPE(func-code,  int-var2,  chni-exp) 


Syntax  Rules 


1.  Func-code  is  an  integer  from  1  through  9  that  specifies  the  code  for  the 
MAGTAPE  function  you  want  to  perform.  MAGTAPE  function  codes 
are  described  in  Table  4-5. 

2.  Int-varl  is  the  value  returned  by  function  codes  4,  5,  7,  and  9. 

3.  Int-varl  is  an  integer  parameter  for  function  codes  4,  5,  and  6. 

•  Int-varl  for  function  4  is  a  value  from  1  through  32767  that 
specifies  the  number  of  records  to  skip. 

•  Int-varl  for  function  5  is  a  value  from  1  through  32767  that 
specifies  the  number  of  records  to  backspace. 

•  Int-varl  for  function  6  specifies  the  density  and/or  parity  of  the 
magnetic  tape  drive. 

4.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  the  magnetic  tape  file.  You  cannot  precede  the 
chnl-exp  with  a  number  sign  (#). 
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MAP 


The  MAP  statement  defines  a  named  area  of  statically  allocated  storage 
called  a  PSECT,  declares  data  fields  in  the  record,  and  associates  them 
with  program  variables. 


Format 


MAP  (map-name)  {  [  data-type  ]  map-item  . 


map-item: 


num-unsubs-var 

num-array-name  ( int-const,  . . .  ) 
str-unsubs-var  [ = int-const  ] 

<  str-array-name  ( int-const  1,  ...  )  [= int-const  ]  ^ 
FILL  [  ( int-const  }][=  int-const  ] 
r\U.%  [( int-const  I  ] 

.  FILLS  [  { int-const  )  ][=  int-const ] 


Syntax  Rules 


1.  Map-name  is  global  to  the  program  and  image.  It  cannot  appear 
elsewhere  in  the  program  unit  as  a  variable  name. 

2.  Map-name  can  be  from  one  through  six  characters.  The  first  character 
of  the  name  must  be  an  alphabetic  character  (A  through  Z).  The 
remaining  characters,  if  present,  can  be  any  combination  of  letters, 
digits  (0  through  9),  dollar  signs  ($ ),  or  periods  ( . ). 

3.  Data-type  can  be  any  BASIC-PLUS-2  data  type  keyword.  Data  type 
keywords,  size,  range,  and  precision  are  listed  in  Table  1-2. 

4.  When  you  specify  a  data  type,  all  following  map-items,  including  FILL 
items,  are  of  that  data  type  until  you  specify  a  new  data  type. 

5.  If  you  specify  a  dollar  sign  ($)  or  percent  sign  (%)  suffix  character, 
the  variable  must  be  a  string  or  integer  data  type,  respectively. 

6.  If  you  do  not  specify  a  data  type,  all  following  map-items  take  the 
current  default  data  type  and  size. 
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7.  Map-item  declares  the  name  and  format  of  the  data  to  be  stored. 

•  Num-unsubs-var  and  num-array-name  specify  a  numeric  variable  or 
a  numeric  array. 

•  Str-unsubs-var  and  str-array-name  specify  a  fixed-length  string 
variable  or  array.  You  can  specify  the  number  of  bytes  to  be 
reserved  for  the  variable  with  the  ^int-const  clause.  The  default 
string  length  is  16. 

•  The  FILL,  FILL%,  and  FILLS  keywords  allow  you  to  reserve  parts 
of  the  record  buffer  within  or  between  data  elements  and  to 
define  the  format  of  the  storage.  Int-const  specifies  the  number 
of  FILL  items  to  be  reserved.  The  =int-const  clause  allows  you  to 
specify  the  number  of  bytes  to  be  reserved  for  string  FILL  items. 
Table  4-2  describes  FILL  item  format  and  storage  allocation. 

•  In  the  applicable  formats  of  FILL,  (int-const)  represents  a  repeat 
count,  not  an  array  subscript.  FILL  (n),  for  example,  represents  n 
elements,  not  n  +  1. 

8.  Variable  names,  array  names,  and  FILL  items  following  a  data  type 
other  than  STRING  cannot  end  with  a  dollar  sign.  Variable  names, 
array  names,  and  FILL  items  following  a  data  type  other  than  BYTE, 
WORD,  LONG,  or  INTEGER  cannot  end  with  a  percent  sign. 

9.  Variables  and  arrays  declared  in  a  MAP  statement  cannot  be  declared 
elsewhere  in  the  program  by  any  other  declarative  statement. 


Remarks 


1.  BASIC-PLUS-2  does  not  execute  MAP  statements.  The  MAP  state¬ 
ment  allocates  static  storage  and  defines  data  at  compilation  time. 

2.  A  program  can  have  multiple  maps  with  the  same  name.  The  allo¬ 
cation  for  each  map  overlays  the  others.  Thus,  data  is  accessible  in 
many  ways.  The  actual  size  of  the  data  area  is  the  size  of  the  largest 
map.  When  you  link  your  program,  the  size  of  the  map  area  is  the 
size  of  the  largest  map  with  that  name. 


f 
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3.  Map-items  with  the  same  name  can  appear  in  different  MAP  state¬ 
ments  with  the  same  map  name  only  if  they  match  exactly  in  at¬ 
tributes  such  as  data  type,  position,  and  so  forth.  If  the  attributes  are 
not  the  same,  BASIC-PLUS-2  signals  an  error.  For  example: 

10  MAP  (ABC)  LONG  A,  B 

MAP  (ABC)  LONG  A,  C  !  This  MAP  statement  Is  valid 

MAP  (ABC)  LONG  B,  A  !  This  MAP  statement  produces  an  error 

MAP  (ABC)  WORD  A,  B  !  This  MAP  statement  produces  an  error 

The  third  MAP  statement  causes  BASIC-PLUS-2  to  signal  the  error 
"Variable  <name>  not  aligned  in  multiple  references  in  MAP 
<name>  ,"  while  the  fourth  MAP  statement  generates  the  error 
"Attributes  of  overlaid  variable  <name>  don't  match." 

4.  The  MAP  statement  should  precede  any  reference  to  variables  declared 
in  it. 

5.  Storage  space  for  map-items  is  allocated  in  order  of  occurrence  in  the 
MAP  statement. 

6.  A  MAP  area  can  be  accessed  by  more  than  one  program  module,  as 
long  as  you  define  the  map-name  in  each  module  that  references  the 
MAP. 

7.  A  COMMON  area  and  a  MAP  area  with  the  same  name  specify  the 
same  storage  area  and  are  not  allowed  in  the  same  program  module; 
however,  a  COMMON  in  one  module  can  reference  the  storage 
declared  by  a  MAP  or  COMMON  in  another  module. 

8.  Variables  in  a  MAP  statement  are  initialized  to  zero  or  a  null  string. 

9.  A  map  named  in  an  OPEN  statement's  MAP  clause  is  associated  with 
that  file.  The  file's  records  and  record  fields  are  defined  by  that  map. 
The  size  of  the  map  determines  the  record  size  for  file  I/O,  unless  the 
OPEN  statement  includes  a  RECORDSIZE  clause. 

10.  The  allocation  for  a  MAP  cannot  exceed  32767  bytes  or 
BASIC-PLUS-2  signals  the  error  "COMMON/MAP  <name>  is  too 
large." 


Example 


10  MAP  (BUFl)  BYTE  AGE,  STRING  emp.name  *  20  b 

SINGLE  emp.num 

MAP  (BUFl)  BYTE  FILL,  STRING  last .name  =12,  A 

FILL  *  8,  SINGLE  FILL 
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MAP  DYNAMIC 


The  MAP  DYNAMIC  statement  names  the  variables  and  arrays  whose 
size  and  position  in  a  storage  area  can  change  at  run  time.  The  MAP 
DYNAMIC  statement  is  used  in  conjunction  with  the  REMAP  statement. 
The  REMAP  statement  defines  or  redefines  the  position  in  the  storage  area 
of  variables  named  in  the  MAP  DYNAMIC  statement. 


Format 

MAP  DYNAMIC  (map-dyn-name){[  data-type  ]map-item  ),  . . . 


map-dyn-name: 


I  map-name  1 
1  static-str-var  } 


map-item: 


'  num-unsubs-var 
num-array-name  ( int-const, 
str-unsubs-var 

.  str-array-name  ( int-const,  . 


Syntax  Rules 


1.  Map-dyn-name  can  be  either  a  map  name  or  a  static  string  variable. 

•  Map-name  is  the  storage  area  named  in  a  MAP  statement. 

•  If  you  specify  a  map  name,  then  a  MAP  statement  with  the  same 
name  must  precede  both  the  MAP  DYNAMIC  statement  and  the 
REMAP  statement. 

•  When  you  specify  a  static  string  variable,  the  string  must  be 
declared  before  you  can  specify  a  MAP  DYNAMIC  statement  or  a 
REMAP  statement. 

•  Static-str-var  must  specify  a  static  string  variable  or  a  string 
parameter  variable. 
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•  If  you  specify  a  static-str-var,  the  following  restrictions  apply: 

—  Static-str-var  cannot  be  a  string  constant. 

—  Static-str-var  cannot  be  the  same  as  any  previously  declared 
map-item  in  a  MAP  DYNAMIC  statement. 

—  Static-str-var  cannot  be  a  subscripted  variable. 

2.  Map-item  declares  the  name  and  data  type  of  the  items  to  be  stored  in 
the  storage  area.  All  variable  pointers  point  to  the  beginning  of  the 
storage  area  until  the  program  executes  a  REMAP  statement. 

•  Num-unsubs-var  and  num-array-name  specify  a  numeric  variable  or 
a  numeric  array. 

•  Str-unsubs-var  and  str-array-name  specify  a  string  variable  or 
array.  You  cannot  specify  the  number  of  bytes  to  be  reserved  for 
the  variable  in  the  MAP  DYNAMIC  statement.  All  string  items 
have  a  fixed  length  of  zero  until  the  program  executes  a  REMAP 
statement. 

3.  Data-type  can  be  any  BASIC-PLUS-2  data  type  keyword.  Data  type 
keywords,  size,  range,  and  precision  are  listed  in  Table  1-2  in  this 
manual. 

4.  When  you  specify  a  data  type,  all  following  map-items  are  of  that  data 
type  until  you  specify  a  new  data  type. 

5.  If  you  do  not  specify  any  data  type,  map-items  take  the  current  default 
data  type  and  size. 

6.  Map-items  must  be  separated  with  commas. 

7.  If  you  specify  a  dollar  sign  or  percent  sign  suffix,  the  variable  must  be 
either  a  STRING  data  type  or  an  integer  data  type,  respectively. 


Remarks 


1.  All  variables  and  arrays  declared  in  a  MAP  DYNAMIC  statement 
cannot  be  declared  elsewhere  in  the  program  by  any  other  declarative 
statements. 

2.  The  MAP  DYNAMIC  statement  does  not  affect  the  amount  of  storage 
allocated  to  the  map  buffer  declared  in  a  previous  MAP  statement  or 
the  storage  allocated  to  a  static  string.  Until  your  program  executes  a 
REMAP  statement,  all  variable  and  array  element  pointers  point  to  the 
beginning  of  the  MAP  buffer  or  static  string. 
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3.  BASIC-PLUS-2  does  not  execute  MAP  DYNAMIC  statements.  The 
MAP  DYNAMIC  statement  names  the  variables  whose  size  and 
position  in  the  MAP  or  static  string  buffer  can  change  and  defines 
their  data  type. 

4.  Before  you  can  specify  a  map  name  in  a  MAP  DYNAMIC  state¬ 
ment,  there  must  be  a  MAP  statement  in  the  program  unit  with  the 
same  map  name;  otherwise,  BASIC-PLUS-2  signals  the  error  "MAP 
DYNAMIC  <map-name>  requires  MAP  or  static  string."  Similarly, 
before  you  can  specify  a  static  string  variable  in  the 

MAP  DYNAMIC  statement,  the  string  variable  must  be  declared; 
otherwise,  BASIC-PLUS-2  signals  the  same  error  message. 

5.  A  static  string  variable  must  be  either  a  variable  declared  in  a 
MAP  or  COMMON  statement  or  a  parameter  declared  in  a  SUB 

or  FUNCTION.  It  cannot  be  a  parameter  declared  in  a  DEF  or  DEF* 
function. 

6.  The  MAP  DYNAMIC  statement  must  lexically  precede  the  REMAP 
statement  or  BASIC-PLUS-2  signals  the  error  "MAP  variable 

<name>  referenced  before  declaration." 


Example 


100  MAP  (MY.BUF)  STRING  DUMMY  *  512 

MAP  DYNAMIC  (MY.BUF)  STRING  LAST.  FIRST.  MIDDLE.  k 

BYTE  AGE.  STRING  EMPLOYER.  k 

STRING  CHARACTERISTICS 
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The  MAT  statement  lets  you  implicitly  create  and  manipulate  one-  and 
two-dimensional  arrays.  You  can  use  the  MAT  statement  to  assign  values 
to  array  elements,  or  to  redimension  a  previously  dimensioned  array. 

You  can  also  perform  matrix  arithmetic  operations  such  as  multiplication, 
addition,  and  subtraction,  and  other  matrix  operations  such  as  transposing 
and  inverting  matrices. 


Format 

Numeric  Initialization 

f  CON  1 

MAT  num-array=  <  IDN  \  [  ( int-expl  [,  int-exp2] )] 

I  ZER  J 

String  Initialization 

MAT  str-array  =  NUL$  [  ( int-expl  [,  int-exp2 ] }  ] 

Array  Arithmetic 


MAT  num-arrayl  =  num-array2 


num-array3 


Scalar  Multiplication 

MAT  num-array4  =  ( num-exp )  *  num-arrayS 

Inversion  and  Transposition 


MAT  num-array6  =  ^  ( num-array?) 
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Syntax  Rules 


1.  Int-expl  and  int-expl  define  the  upper  bounds  of  the  array  being 
implicitly  created  or  the  new  dimensions  of  an  existing  array. 

2.  You  cannot  use  the  MAT  statement  on  arrays  of  more  than  two 
dimensions. 

3.  If  you  are  creating  an  array,  int-expl  and  int-expl  cannot  exceed  10. 

4.  If  you  do  not  specify  bounds,  BASIC-PLUS-2  creates  the  array  and 
dimensions  it  to  (10)  or  (10,10). 

5.  If  you  specify  bounds,  BASIC-PLUS-2  creates  the  array  with  the 
specified  bounds.  If  the  bounds  exceed  (10)  or  (10,10),  BASIC-PLUS-2 
signals  the  error  "Redimensioned  array"  (ERR=105). 


Remarks 


1.  To  perform  MAT  operations  on  arrays  larger  than  (10,10),  create  the 
input  and  output  arrays  with  the  DIM  statement. 

2.  You  cannot  increase  the  number  of  array  elements  or  change  the 
number  of  dimensions  in  an  array  when  you  redimension  with  the 
MAT  statement.  For  example,  you  can  redimension  an  array  with 
dimensions  ( 5,4 )  to  ( 4,5 )  or  ( 3,2 ),  but  you  cannot  redimension  that 
array  to  (5,5)  or  to  ( 10).  The  total  number  of  array  elements  includes 
those  in  row  and  column  zero. 

3.  If  an  array  is  named  in  both  a  DIM  statement  and  a  MAT  statement, 
the  DIM  statement  must  lexically  precede  the  MAT  statement. 

4.  MAT  statements  do  not  operate  on  elements  in  the  zero  element  (one¬ 
dimensional  arrays)  or  in  the  zero  row  or  column  (two-dimensional 
arrays).  MAT  statements  use  these  elements  to  store  results  of  inter¬ 
mediate  calculations.  Therefore,  you  should  not  depend  on  values  in 
row  and  column  zero  if  your  program  uses  MAT  statements. 

5.  When  the  array  exists,  the  following  rules  apply: 

•  If  you  specify  bounds,  BASIC-PLUS-2  redimensions  the  array  to 
the  specified  size;  however,  MAT  operations  cannot  increase  the 
total  number  of  array  elements. 

•  If  you  do  not  specify  bounds,  BASIC-PLUS-2  does  not  redimen¬ 
sion  the  array. 
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6.  Initialization 

•  CON  sets  all  elements  of  num-array  to  1,  except  those  in  row  and 
column  zero. 

•  IDN  creates  an  identity  matrix  from  num-array.  The  number  of 
rows  and  columns  in  num-array  must  be  identical.  IDN  sets  all 
elements  to  zero  except  those  on  the  diagonal  from  num-array{l,l) 
to  num-array{T\,n),  which  are  set  to  1. 

•  ZER  sets  all  array  elements  to  zero,  except  those  in  row  and 
column  zero. 

•  NUL$  sets  all  elements  of  a  string  array  to  the  null  string,  except 
those  in  row  and  column  zero. 

7.  Array  Arithmetic 

•  The  equal  sign  (=)  assigns  the  results  of  the  specified  operation  to 
the  elements  in  num-arrayl. 

•  If  num-array3  is  not  specified,  BASIC-PLUS-2  assigns  the  values  of 
num-arrayl's  elements  to  the  corresponding  elements  of 
num-arrayl.  Num-arrayl  must  have  at  least  as  many  rows  and 
columns  as  num-arrayl. 

•  Use  the  plus  sign  (+)  to  add  the  elements  of  two  arrays. 
Num-arrayl  and  num-array3  must  have  identical  bounds. 

•  Use  the  minus  sign  (-)  to  subtract  the  elements  of  two  arrays. 
Num-arrayl  and  num-array3  must  have  identical  bounds. 

•  Use  the  asterisk  ( * )  to  perform  matrix  multiplication  on  the 
elements  of  num-arrayl  and  num-array3  and  to  assign  the  results 
to  num-arrayl.  This  operation  gives  the  dot  product  of  num-arrayl 
and  num-array3.  All  three  arrays  must  be  two-dimensional,  and 
the  number  of  columns  in  num-arrayl  must  equal  the  number 

of  rows  in  num-array3.  BASIC-PLUS-2  redimensions  num-arrayl 
to  have  the  same  number  of  rows  as  num-arrayl  and  the  same 
number  of  columns  as  num-array3. 

•  You  cannot  perform  matrix  multiplication  with  the  same  array 
as  both  the  source  and  destination,  or  BASIC-PLUS-2  signals  an 
error. 

8.  Scalar  Multiplication 

BASIC-PLUS-2  multiplies  each  element  of  num-arrayS  by  num-exp  and 

stores  the  results  in  the  corresponding  elements  of  num-array4. 
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9.  Inversion  and  Transposition 

•  TRN  transposes  num-array?  and  assigns  the  results  to  num-array6. 
If  num-array7  has  m  rows  and  n  columns,  num-arrayS  will  have  n 
rows  and  m  columns.  Both  arrays  must  be  two-dimensional. 

•  You  cannot  transpose  a  matrix  to  itself:  MAT  A  =  TRN(A)  is 
invalid. 

•  INV  inverts  num-array?  and  assigns  the  results  to  num-array6. 
Num-array?  must  be  a  two-dimensional  array  that  can  be  reduced 
to  the  identity  matrix  with  elementary  row  operations.  The  row 
and  column  dimensions  must  be  identical. 

•  You  cannot  use  the  MAT  statement  to  invert  an  array  with  a 
datatype  of  LONG  or  BYTE,  or  to  invert  an  array  received  as  a 
parameter. 


Examples 


Example  1 

10  ! Numeric  Initialization 

MAT  CONVERT  -  zerdO.lO) 

Example  2 

10  ! Initialization 

MAT  na.mel  >  NUL$(5.5) 

Example  3 

! Array  Arithmetic 

MAT  new.int  *  old_int  -  rslt.int 

Example  4 

10  ! Scalar  Multiplication 

MAT  Z40^«  (4.24)  ♦  Z 

Example  5 

10  ! Inversion  and  Transposition 

MAT  Q%  *  INV  (Z) 
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The  MAT  INPUT  statement  assigns  values  from  a  terminal  or  terminal- 
format  file  to  array  elements. 


Format 

MAT  INPUT  [ #chnl-exp,  ]  { array  [  ( int-expl  [,  int-exp2 ])]),  . . . 


Syntax  Rules 


1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 

2.  The  file  associated  with  chnl-exp  must  be  an  open  terminal-format 
file  or  terminal.  If  chnl-exp  is  not  specified,  BASIC-PLUS-2  takes  data 
from  the  controlling  terminal. 

3.  Int-expl  and  int-expl  define  the  upper  bounds  of  the  array  being 
implicitly  created  or  the  dimensions  of  an  existing  array. 

4.  If  you  are  creating  an  array,  int-expl  and  int-expl  cannot  exceed  10. 


Remarks 


1.  You  cannot  use  the  MAT  INPUT  statement  on  arrays  of  more  than 
two  dimensions. 

2.  If  you  do  not  specify  bounds,  BASIC-PLUS-2  creates  the  array  and 
dimensions  it  to  (10,10). 

3.  If  you  do  specify  bounds,  BASIC-PLUS-2  creates  the  array  with  the 
specified  bounds.  If  the  bounds  exceed  ( 10)  or  (10,10), 
BASIC-PLUS-2  signals  the  error  "Redimensioned  array"  (ERR=105). 

4.  To  use  the  MAT  INPUT  statement  with  arrays  larger  than  (10,10), 
create  the  input  and  output  arrays  with  the  DIM  statement. 
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5.  When  the  array  exists,  the  following  rules  apply: 

•  If  you  specify  bounds,  BASIC-PLUS-2  redimensions  the  array  to 
the  specified  size;  however,  MAT  INPUT  cannot  increase  the  total 
number  of  array  elements. 

•  If  you  do  not  specify  bounds,  BASIC-PLUS-2  does  not  redimen¬ 
sion  the  array. 

6.  Unless  a  SET  NO  PROMPT  statement  has  been  executed,  the  MAT 
INPUT  statement  prompts  with  a  question  mark  on  terminals  open  on 
channel  #0  only.  See  the  description  of  the  SET  PROMPT  statement 
for  more  information. 

7.  Use  commas  to  separate  data  elements  and  a  line  terminator  to  end 
the  input  of  data.  Use  an  ampersand  (&)  before  the  line  terminator  to 
continue  data  over  more  than  one  line. 

8.  The  MAT  INPUT  statement  assigns  values  by  row.  For  example,  it 
assigns  values  to  all  elements  in  row  1  before  beginning  row  2. 

9.  The  MAT  INPUT  statement  assigns  the  row  number  of  the  last  data 
element  transferred  into  the  array  to  the  system  variable  NUM. 

10.  The  MAT  INPUT  statement  assigns  the  column  number  of  the  last 
data  element  transferred  into  the  array  to  the  system  variable  NUM2. 

11.  If  there  are  fewer  elements  in  the  input  data  than  there  are  array  ele¬ 
ments,  BASIC-PLUS-2  does  not  change  the  remaining  array  elements. 

12.  If  there  are  more  data  elements  in  the  input  stream  than  there  are 
array  elements,  BASIC-PLUS-2  ignores  the  excess. 

13.  Row  zero  and  column  zero  are  not  changed. 


Example 


10  MAT  INPUT  XYZ(6,6) 
MAT  PRINT  XYZ; 

Output 

?  1,2, 3, 4, 6 

1  2  3  4  5 

0  0  0  0  0 

0  0  0  0  0 

0  0  0  0  0 

0  0  0  0  0 
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The  MAT  LINPUT  statement  receives  string  data  from  a  terminal  or 
terminal-format  file  and  assigns  it  to  string  array  elements. 


Format 

MAT  LINPUT  [ #chnl-exp,  ]  { str-array  [  ( int-expl  [,  int-exp2 ])]},... 


Syntax  Rules 


1.  ChnUexp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file  or  terminal.  It  must  be  immediately  preceded  by 
a  number  sign  (#). 

2.  The  file  associated  with  chnUexp  must  be  an  open  terminal-format  file 
or  terminal.  If  a  channel  is  not  specified,  BASIC-PLUS-2  takes  data 
from  the  controlling  terminal. 

3.  Int-expl  and  int-expl  define  the  upper  bounds  of  the  array  being 
implicitly  created  or  the  dimensions  of  an  existing  array. 

4.  If  you  are  creating  an  array,  int-expl  and  int-expl  cannot  exceed  10. 


Remarks 


1.  You  cannot  use  the  MAT  LINPUT  statement  on  arrays  of  more  than 
two  dimensions. 

2.  If  you  do  not  specify  bounds,  BASIC-PLUS-2  creates  the  array  and 
dimensions  it  to  (10,10). 

3.  If  you  do  specify  upper  bounds,  BASIC-PLUS-2  creates  the  array 
with  the  specified  bounds.  If  the  bounds  exceed  (10)  or  (10,10), 
BASIC-PLUS-2  signals  the  error  "Redimensioned  array"  (ERR==105). 

4.  To  use  MAT  LINPUT  with  arrays  larger  than  (10,10),  create  the  input 
and  output  arrays  with  the  DIM  statement. 
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5.  When  the  array  exists,  the  following  rules  apply: 

•  If  you  specify  bounds,  BASIC-PLUS-2  redimensions  the  array  to 
the  specified  size;  however,  MAT  LINPUT  cannot  increase  the 
total  number  of  array  elements. 

•  If  you  do  not  specify  bounds,  BASIC-PLUS-2  does  not  redimen¬ 
sion  the  array. 

6.  Unless  a  SET  NO  PROMPT  statement  has  been  executed,  the  MAT 
LINPUT  statement  prompts  with  a  question  mark  for  each  string  array 
element  for  terminals  open  on  channel  zero.  BASIC-PLUS-2  assigns 
values  to  all  elements  of  row  1  before  beginning  row  2. 

7.  The  MAT  LINPUT  statement  assigns  the  row  number  of  the  last  data 
element  transferred  into  the  array  to  the  system  variable  NUM. 

8.  The  MAT  LINPUT  statement  assigns  the  column  number  of  the  last 
data  element  transferred  into  the  array  to  the  system  variable  NUM2. 

9.  Typing  only  a  line  terminator  in  response  to  the  question  mark 
prompt  causes  BASIC-PLUS-2  to  assign  a  null  string  to  that  string 
array  element. 

10.  Like  the  MAT  INPUT  statement,  the  MAT  LINPUT  statement  nor¬ 
mally  accepts  only  a  single  line  of  input  from  an  input  file.  To  supply 
more  than  one  line  of  input,  you  must  use  an  ampersand  ( & )  before 
the  line  terminator. 

11.  MAT  LINPUT  does  not  change  row  and  column  zero. 


Example 


10  DIM  cu8_rec$(3,3) 

MAT  LINPUT  cu8_rec$(2.2) 
PRINT  cu8_rec|(l,l) 

PRINT  cu8_rec$(1.2) 

PRINT  cu8_rec$(2.1) 

PRINT  cu8_rec$(2,2) 
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Output 

7  Babcock 
?  Santanl 
?  Lloyd 
?  Kelly 
Babcock 
Santani 

Lloyd 

Kelly 
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MAT  PRINT 


The  MAT  PRINT  statement  prints  the  contents  of  a  one-  or  two- 
dimensional  array  on  your  terminal  or  assigns  the  value  of  each  array 
element  to  a  record  in  a  terminal-format  file. 


Format 


MAT  PRINT  [ #chnl-exp,  ]  ( array [  ( int-expl  [,  int-exp2 ])] 


}... 


Syntax  Rules 


1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file  or  terminal.  It  must  be  immediately  preceded  by 
a  number  sign  ( # ). 

2.  The  file  associated  with  chnl-exp  must  be  an  open  terminal-format  file 
or  terminal.  If  you  do  not  specify  a  channel,  BASIC-PLUS-2  takes 
data  from  the  controlling  terminal. 

3.  Int-expl  and  int-expl  define  the  upper  bounds  of  the  array  being 
implicitly  created  or  the  dimensions  of  an  existing  array. 

4.  The  separator  (comma  or  semicolon)  determines  the  output  format  for 
the  array: 

•  If  you  use  a  comma,  BASIC-PLUS-2  prints  each  array  element  in 
a  new  print  zone  and  starts  each  row  on  a  new  line. 

•  If  you  use  a  semicolon,  BASIC-PLUS-2  separates  each  array 
element  with  a  space  and  starts  each  row  on  a  new  line. 

•  If  you  do  not  use  a  separator  character,  BASIC-PLUS-2  prints  each 
array  element  on  its  own  line. 
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Remarks 


1.  You  cannot  use  the  MAT  PRINT  statement  on  arrays  of  more  than 
two  dimensions. 

2.  When  you  use  the  MAT  PRINT  statement  to  print  more  than  one 
array,  each  array  name  except  the  last  must  be  followed  with  either 
a  comma  or  a  semicolon.  BASIC-PLUS-2  prints  a  blank  line  between 
arrays. 

3.  If  the  array  does  not  exist,  the  following  rules  apply: 

•  If  you  do  not  specify  bounds,  BASIC-PLUS-2  creates  the  array  and 
dimensions  it  to  (10,10). 

•  If  you  specify  bounds,  BASIC-PLUS-2  creates  the  array  with  the 
specified  bounds.  If  the  bounds  exceed  ( 10)  or  (10,10), 
BASIC-PLUS-2  prints  the  elements  ( 10 )  or  (10,10),  and  signals 
the  error  'Subscript  out  of  range"  (ERR=55). 

4.  When  the  array  exists,  the  following  rules  apply: 

•  If  the  specified  bounds  are  smaller  than  the  maximum  bounds  of 
a  dimensioned  array,  BASIC-PLUS-2  prints  a  subset  of  the  array, 
but  does  not  redimension  the  array.  For  example,  if  you  use  the 
DIM  statement  to  dimension  A(20,20),  and  then  MAT  PRINT 
A(2,2),  BASIC-PLUS-2  prints  elements  (1,1),  (1,2),  (2,1),  and 

( 2,2 )  only;  array  A(20,20)  does  not  change. 

•  If  you  do  not  specify  bounds,  BASIC-PLUS-2  prints  the  entire 
array. 

5.  The  MAT  PRINT  statement  does  not  print  elements  in  row  or  column 
zero. 

6.  The  MAT  PRINT  statement  cannot  redimension  an  array. 
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Example 

V 

10  DIM  cu8_rec$(3,3) 

MAT  LINPUT  cu8_rec$(2.2) 

MAT  PRINT  cu8_rec$(2.2) 

Output 

7  Babcock 

7  Santani 
?  Lloyd 
?  Kelly 

Babcock 

Santani 

Lloyd 

Kelly 
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The  MAT  READ  statement  assigns  values  from  DATA  statements  to  array 
elements. 


Format 

MAT  READ  {  array  [  ( int-exp  1  [,  int-exp2  ] }  ]  },  . . . 


Syntax  Rules 

1.  Int-expl  and  int-exp2  define  the  upper  bounds  of  the  array  being 
implicitly  created  or  the  dimensions  of  an  existing  array. 

2.  If  you  are  creating  an  array,  int-expl  and  int-exp2  cannot  exceed  10. 


Remarks 


1.  If  you  do  not  specify  bounds,  BASIC-PLUS-2  creates  the  array  and 
dimensions  it  to  (10)  or  (10,10). 

2.  If  you  specify  bounds,  BASIC-PLUS-2  creates  the  array  with  the 
specified  bounds.  If  the  bounds  exceed  ( 10)  or  (10,10), 
BASIC-PLUS-2  signals  the  error  "Redimensioned  array"  (ERR=105). 

3.  To  read  arrays  larger  than  (10,10),  create  the  array  with  the  DIM 
statement. 

4.  When  the  array  exists,  the  following  rules  apply: 

•  If  you  specify  bounds,  BASIC-PLUS-2  redimensions  the  array  to 
the  specified  size;  however,  MAT  READ  cannot  increase  the  total 
number  of  array  elements. 

•  If  you  do  not  specify  bounds,  BASIC-PLUS-2  does  not  redimen¬ 
sion  the  array. 

5.  All  the  DATA  statements  must  be  in  the  same  program  unit  as  the 
MAT  READ  statement. 
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6.  The  MAT  READ  statement  assigns  data  items  by  row.  For  example,  it 
assigns  data  items  to  all  elements  in  row  1  before  beginning  row  2. 

7.  The  MAT  READ  statement  does  not  read  elements  into  row  or  column 
zero. 

8.  The  MAT  READ  statement  assigns  the  row  number  of  the  last  data 
element  transferred  into  the  array  to  the  system  variable  NUM. 

9.  The  MAT  READ  statement  assigns  the  column  number  of  the  last  data 
element  transferred  into  the  array  to  the  system  variable  NUM2. 

10.  If  you  use  MAT  READ  for  an  existing  array  without  specifying  bounds, 
BASIC-PLUS-2  does  not  redimension  the  array.  If  you  use  MAT 
READ  for  an  existing  array  and  specify  bounds,  BASIC-PLUS-2 
redimensions  the  array. 

11.  You  cannot  use  the  MAT  READ  statement  on  arrays  of  more  than  two 
dimensions. 


Example 


10  MAT  READ  A(3.3) 
MAT  READ  6(3.3) 
PRINT 

PRINT  "Matrix  A" 
PRINT 

MAT  PRINT  A; 
PRINT 

PRINT  "Matrix  B" 
PRINT 

MAT  PRINT  B; 

DATA  1.2. 3. 4. 5. 6 

Output 

Matrix  A 

12  3 

4  5  6 

0  0  0 

Matrix  B 

0  0  0 
0  0  0 
0  0  0 
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The  MAX  function  compares  the  values  of  two  or  more  numeric  expres¬ 
sions  and  returns  the  highest  value. 


Format 

num-var  =  fiHKK  (num-expl,  num-exp2  [ ,num-exp3 ,  . . .  ]} 


Syntax  Rules 

BASlC-PLUS-2  allows  you  to  specify  up  to  eight  numeric  expressions. 


Remarks 


1.  If  you  specify  values  with  different  data  types,  BASIC-PLUS-2  per¬ 
forms  data  type  conversions  to  maintain  precision. 

2.  BASIC-PLUS-2  returns  a  function  result  whose  data  type  is  compatible 
with  the  values  you  supply. 


Example 


20  DECLARE  REAL  John_grade,  k 
Bob.grade ,  k 
Joe_grade,  k 
hlghe8t_grade 

30  INPUT  "John's  grade" ;John_grade 
40  INPUT  "Bob's  grade" ;Bob_grade 
60  INPUT  "Joe's  grade" ;Joe.grade 

60  hlghe8t_grade  ■  MAX(John_grade,  Bob^grade.  Joe_grade) 
70  PRINT  "The  highest  grade  is" ;highe8t_grade 
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Output 

John's  grade?  90 
Bob's  grade?  95 
Joe's  grade?  79 
The  highest  grade  is  95 
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The  MID$  function  extracts  a  specified  substring  from  a  string  expression. 


Format 

sfr-raf  =  MID[$]  (str-exp,  int-expl,  int-exp2} 

Syntax  Rules 

1.  Int-expl  specifies  the  position  of  the  substring's  first  character. 

2.  Int-expl  specifies  the  length  of  the  substring. 


Remarks 


1.  If  int-expl  is  less  than  1,  BASIC-PLUS-2  assumes  a  starting  character 
position  of  1. 

2.  If  int-expl  is  less  than  or  equal  to  zero,  BASIC-PLUS-2  assumes  a 
length  of  zero. 

3.  If  you  specify  a  floating-point  expression  for  int-expl  or  int-expl, 
BASIC-PLUS-2  truncates  it  to  a  WORD  integer. 

4.  The  MID$  function  extracts  a  substring  from  str-exp  and  stores  it  in 
str-var. 

5.  If  int-expl  is  greater  than  the  length  of  str-exp,  MID$  returns  a  null 
string. 

6.  If  int-expl  is  greater  than  the  length  of  str-exp,  BASIC-PLUS-2  returns 
the  string  that  begins  at  int-expl  and  includes  all  characters  remaining 
in  str-exp. 

7.  If  int-expl  is  less  than  or  equal  to  zero,  MID$  returns  a  null  string. 
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Example 

10  !MID$  Function 

DECLARE  STRING  old.strlng,  new.strlng 

old.string  ■  "ABCD" 

new.string  *  MIDI (old.string, 1,3) 

PRINT  new.string 

Output 

ABC 
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The  MIN  function  compares  the  values  of  two  or  more  numeric  expres¬ 
sions  and  returns  the  smallest  value. 


Format 

num-var  =  M\U  ( num-expl,  num-exp2  [ ,nuin-exp3 ,...]) 


Syntax  Rules 

BASIC-PLUS-2  allows  you  to  specify  up  to  eight  numeric  expressions. 


Remarks 


1.  If  you  specify  values  with  different  data  types,  BASIC-PLUS-2  per¬ 
forms  data  type  conversions  to  maintain  precision. 

2.  BASIC-PLUS-2  returns  a  function  result  whose  data  type  is  compatible 
with  the  values  you  supply. 


Example 


20  DECLARE  REAL  John.grade,  k 
Bob.grade .  k 
Joe_grade,  k 
lowe8t_grade 

30  INPUT  "John's  grade" ;Jobn_grade 
40  INPUT  "Bob's  grade" ;Bob_grade 
60  INPUT  "Joe's  grade" ;Joe_grade 

60  lowest .grade  ■  MIN(John.grade.  Bob_grade.  Joe_grade) 
70  PRINT  "The  lowest  grade  is" ;lowe8t_grade 
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Output 

John's  grade?  95 
Bob's  grade?  100 
Joe's  grade?  84 
The  lowest  grade  Is  84 
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The  MOD  function  divides  a  numeric  value  by  another  numeric  value  and 
returns  the  remainder. 


Format 

num-var  =  MOD  ( num-expl,  num-exp2 ) 


Syntax  Rules 

None. 


Remarks 


1.  Num-expl  is  divided  by  num-exp2. 

2.  If  you  specify  values  with  different  data  types,  BASIC-PLUS-2  per¬ 
forms  data  type  conversions  to  maintain  precision. 

3.  BASIC-PLUS-2  returns  a  function  result  whose  data  type  is  compatible 
with  the  values  you  supply. 

4.  The  function  result  is  either  a  positive  or  negative  value,  depending 
on  the  value  of  the  first  numeric  expression.  For  example,  if  the  first 
numeric  expression  is  negative,  then  the  function  result  will  also  be 
negative. 


Example 


10  DECLARE  REAL  A.B 
20  A  *  500 
30  B  *  MOD (A. 70) 

40  PRINT  "The  remainder  equals" ;B 
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The  remainder  equals  10 


MOD 
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The  MOVE  statement  transfers  data  between  a  record  buffer  and  a  list  of 
variables. 

Format 

MOVE  (  1 

1  FROM  j 

#chnl-exp,  move-item,  ... 

move-item:  < 

'  num-var 

num-array  ([,]...) 
str-var  [ = int-exp  ] 
str-array  ([,]...)[= int-exp  ] 

[  data-type  ]  FILL  [  ( int-exp  )][= int-const  ] 
f \IL%  [( int-exp )  ] 

.  FILLS  [  ( int-exp }  ]  [= int-exp  ] 

Syntax  Rules 


1.  Chnl-exp  is  a  Viumeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 

2.  Move-item  specifies  the  variable  or  array  to  which  or  from  which  data 
is  to  be  moved. 

3.  Parentheses  indicate  the  number  of  dimensions  in  a  numeric  array. 
The  number  of  dimensions  is  equal  to  the  number  of  commas  plus 
1.  Empty  parentheses  indicate  a  one-dimensional  array,  one  comma 
indicates  a  two-dimensional  array,  and  so  on. 
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4.  Str-var  and  str-array  specify  a  fixed-length  string  variable  or  array. 
Parentheses  indicate  the  number  of  dimensions  in  a  string  array.  The 
number  of  dimensions  is  equal  to  the  number  of  commas  plus  1.  You 
can  specify  the  number  of  bytes  to  be  reserved  for  the  variable  or 
array  elements  with  the  =int-exp  clause.  The  default  string  length  for  a 
MOVE  FROM  statement  is  16.  For  a  MOVE  TO  statement,  the  default 
is  the  string's  length. 

5.  The  FILL,  FILL%,  and  FILLS  keywords  allow  you  to  transfer  fill 
items  of  a  specific  data  type.  Table  4-2  shows  FILL  item  formats, 
representations,  and  storage  requirements. 

•  If  you  specify  a  data  type  before  the  FILL  keyword,  the  fill  is  of 
that  data  type.  If  you  do  not  specify  a  data  type,  the  fill  is  of  the 
default  data  type.  Data-type  can  be  any  BASIC-PLUS-2  data  type 
keyword.  Data  type  keywords,  size,  range,  and  precision  are  listed 
in  Table  1-2  in  this  manual. 

•  FILL  items  following  a  data  type  other  than  STRING  cannot  end 
with  a  dollar  sign.  FILL  items  following  a  data  type  other  than 
BYTE,  WORD,  LONG,  or  INTEGER  cannot  end  with  a  percent 
sign. 

•  Int-exp  specifies  the  number  of  FILL  items  to  be  moved. 

•  FILL%  indicates  integer  fill.  FILL$  indicates  string  fill.  The 
=int-exp  clause  specifies  the  number  of  bytes  to  be  moved  for 
string  FILL  items. 

•  In  the  applicable  formats  of  FILL,  (int-exp)  represents  a  repeat 
count,  not  an  array  subscript.  FILL  (n),  for  example,  represents  n 
elements,  not  «  +  1. 

6.  You  cannot  use  an  expression  or  function  reference  as  a  move-item. 


Remarks 


f  •  Before  a  MOVE  FROM  statement  can  execute,  the  file  associated  with 
chnl-exp  must  be  open  and  there  must  be  a  record  in  the  record  buffer. 

2.  A  MOVE  statement  neither  transfers  data  to  or  from  external  devices, 
nor  invokes  the  Record  Management  Services  (RMS).  Instead,  it 
transfers  data  between  user  areas.  Thus,  a  record  should  first  be 
fetched  with  the  GET  statement  before  you  use  a  MOVE  FROM 
statement,  and  a  MOVE  TO  statement  should  be  followed  by  a  PUT 
or  UPDATE  statement  that  writes  the  record  to  a  file. 

3.  MOVE  FROM  transfers  data  from  the  record  buffer  to  the  move-item. 
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4.  MOVE  TO  transfers  data  from  the  move-item  to  the  record  buffer. 

5.  The  MOVE  statement  does  not  affect  the  record  buffer's  size.  If 
a  MOVE  statement  partially  fills  a  buffer,  the  rest  of  the  buffer  is 
unchanged.  If  there  is  more  data  in  the  variable  list  than  in  the  buffer, 
BASIC-PLUS-2  signals  the  error  "MOVE  overflows  buffer"  (ERR=161). 

6.  Each  MOVE  statement  to  or  from  a  channel  transfers  data  starting  at 
the  beginning  of  the  buffer.  For  example: 

100  MOVE  FROM  #1%.  1%.  A$  -  1% 

In  this  example,  BASIC-PLUS-2  assigns  the  first  value  in  the  record 
buffer  to  1%;  the  value  of  1%  is  then  used  to  determine  the  length  of 
A$. 

7.  If  a  MOVE  statement  operates  on  an  entire  array,  the  following 
conditions  apply: 

•  BASIC-PLUS-2  transfers  elements  of  row  and  column  zero  (in 
contrast  to  the  MAT  statements). 

•  The  storage  size  of  the  array  elements  and  the  size  of  the  array 
determine  the  amount  of  data  moved.  A  MOVE  statement  that 
transfers  data  from  the  buffer  to  a  longword  integer  array  transfers 
the  first  four  bytes  of  data  into  the  first  element  (for  example, 
(0,0)),  the  next  four  bytes  of  data  into  element  (0,1 ),  and  so  on. 

8.  If  the  MOVE  TO  statement  specifies  an  explicit  string  length,  the 
following  restrictions  apply: 

•  If  the  string  is  equal  to  or  longer  than  the  explicit  string  length, 
BASIC -PLUS-2  moves  only  the  specified  number  of  characters 
into  the  buffer. 

•  If  the  string  is  shorter  than  the  explicit  string  length, 

BASIC -PLUS-2  moves  the  entire  string  and  pads  it  with  spaces  to 
the  specified  length. 

9.  BASIC-PLUS-2  does  not  check  the  validity  of  data  during  the  MOVE 
operation. 
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Examples 


Example  1 

20  MOVE  FROM  #4X,  RUNSX.  HITSX,  ERRORSX.  RBIX,  BAT_AVERACE 

Example  2 

100  MOVE  TO  »9%.  FILL!  -  lOX.  A$  -  10%,  B$  •  30X.  C$  •  2X 
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The  NAME  ...  AS  statement  renames  the  specified  file. 


Format 

NAME  file-speci  AS  file-spec2 


Syntax  Rules 

1.  File-sped  and  file-sped  must  be  string  expressions. 

2.  There  is  no  default  file  type  in  file-sped  or  file-sped.  If  the  file  to  be 
renamed  has  a  file  type,  file-sped  must  include  both  the  file  name  and 
the  file  type. 

3.  If  you  specify  only  a  file  name,  BASIC-PLUS-2  searches  for  a  file 
with  no  file  type.  If  you  do  not  specify  a  file  type  for  file-sped, 
BASIC-PLUS-2  names  the  file  but  does  not  assign  a  file  type. 

4.  If  you  specify  a  directory  name  with  file-sped,  the  file  will  be  placed 
in  the  specified  directory.  If  you  do  not  specify  a  directory  name,  the 
default  is  the  current  directory. 

5.  On  RSX  systems,  file  version  numbers  are  optional.  BASIC-PLUS-2 
renames  the  highest  version  of  file-sped  if  you  do  not  specify  a 
version  number. 


Remarks 


1.  If  the  file  specified  by  file-sped  does  not  exist,  BASIC-PLUS-2  signals 
the  error  "Can't  find  file  or  account"  (ERR=5). 

2.  If  you  use  the  NAME  ...  AS  statement  on  an  open  file, 
BASIC-PLUS-2  does  not  rename  the  file  until  it  is  closed. 
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3.  You  cannot  use  the  NAME  ...  AS  statement  to  move  a  file  between 
devices.  You  can  only  change  the  directory,  name,  type,  or  ver¬ 
sion  number.  If  you  specify  a  new  device  with  the  NAME  ...  AS 
statement,  BASIC-PLUS-2  signals  the  error  "Illegal  usage  for  device" 
(ERR=133). 


Example 


400  NAME  "OLDPRC.BAS”  AS  "NEWPRG.BAS' 
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The  NEXT  statement  marks  the  end  of  a  FOR,  UNTIL,  or  WHILE  loop. 


Format 

NEXT  [  num-unsubs-var  ] 


Syntax  Rules 

1.  Num-unsubs-var  is  required  in  a  FOR  .  . .  NEXT  loop  and  must  corre¬ 
spond  to  the  num-unsubs-var  specified  in  the  FOR  statement. 

2.  Num-unsubs-var  is  not  allowed  in  an  UNTIL  or  WHILE  loop. 

3.  Num-unsubs-var  must  be  a  numeric,  unsubscripted  variable. 


Remarks 


Each  NEXT  statement  must  have  a  corresponding  FOR,  UNTIL,  or  WHILE 
statement,  or  BASIC-PLUS-2  signals  an  error. 


Example 


10  PROGRAM  calculatlng.pay 

DECLARE  INTEGER  no.hours.  k 

SINGLE  weekly_pay.  minimum_wage 
minlmum.wage  »  3.65 
no.hours  *  40 
WHILE  no.hours  >  0 

INPUT  "Enter  the  number  ol  hours  you  Intend  to  work  this  week" ;no_hours 
weekly.pay  *  no_hours  *  minimum.wage 

PRINT  "It  you  worked" ;no_hours; "hours,  your  pay  would  be" ; weekly _pay 
NEXT 

END  PROGRAM 
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NEXT 


Output 

Enter  the  number  of  hours  you  intend  to  work  this  week?  35 

If  you  worked  35  hours,  your  pay  would  be  127.75 

Enter  the  number  of  hours  you  Intend  to  work  this  week?  23 

If  you  worked  23  hours,  your  pay  would  be  83.95 

Enter  the  number  of  hours  you  intend  to  work  this  week?  0 

If  you  worked  0  hours  your  pay  would  be  0 
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NOECHO 


The  NOECHO  function  disables  echoing  of  input  on  a  terminal. 


Format 

int-var  =  fiO£CHO(chnl-exp} 


Syntax  Rules 

Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  an  open  terminal.  It  cannot  be  preceded  by  a  number 
sign  (#). 


Remarks 


1.  If  you  specify  NOECHO,  BASIC-PLUS-2  accepts  characters  typed  on 
the  terminal  as  input,  but  the  characters  do  not  echo  on  the  terminal. 

2.  The  NOECHO  function  is  the  complement  of  the  ECHO  function; 
NOECHO  disables  the  effect  of  ECHO  and  vice  versa. 

3.  NOECHO  always  returns  a  value  of  zero. 


Example 


10  DECLARE  INTEGER  Y.  k 

STRING  pass.word 

Y  *  NOECHO (0) 

INPUT  "Enter  your  password" ; pas s.word 
IF  pass.word  *  "DARLENE"  THEN  PRINT  "Confirmed" 

Y  =  ECHO(O) 

Output 

Enter  your  password? 

Confirmed 
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MUM 


niUM 


The  NUM  function  returns  the  row  number  of  the  last  data  element 
transferred  into  an  array  by  a  MAT  I/O  statement. 


Format 

int-var  =  K\iM 


Syntax  Rules 

None. 


Remarks 


1.  NUM  returns  a  value  of  zero  if  it  is  invoked  before  BASIC-PLUS-2 
has  executed  any  MAT  I/O  statements. 

2.  For  a  two-dimensional  array,  NUM  returns  an  integer  specifying  the 
row  number  of  the  last  data  element  transferred  into  the  array.  For  a 
one-dimensional  array,  NUM  returns  the  number  of  elements  entered. 

3.  The  value  returned  by  the  NUM  function  is  an  integer  of  the  default 
size. 


Example 


10  OPEN  "ACCT"  FOR  INPUT  AS  #2 
DIM  8tu_rec$(3,3) 

MAT  INPUT  #2.  8tu_rec$ 

PRINT  "Row  count  «";NUM 
PRINT  "Column  number  =";NUM2 

Output 

Row  count  *  1 
Column  number  »  1 
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MUM2 


The  NUM2  function  returns  the  column  number  of  the  last  data  element 
transferred  into  an  array  by  a  MAT  I/O  statement. 


Format 

int-var  =  NUM2 

Syntax  Rules 

None. 

Remarks 


1.  NUM2  returns  a  value  of  zero  if  it  is  invoked  before  BASIC-PLUS-2 
has  executed  any  MAT  I/O  statements  or  if  the  last  array  element 
transferred  was  in  a  one-dimensional  list. 

2.  The  NUM2  function  returns  an  integer  specifying  the  column  number 
of  the  last  data  element  transferred  into  an  array. 

3.  The  value  returned  by  the  NUM2  function  is  an  integer  of  the  default 
size. 


Example 


10  OPEN  "ACCT"  FOR  INPUT  AS  #2 
DIM  8tu_rec$(3.3) 

MAT  INPUT  #2,  stu.reci 
PRINT  "Row  count  «";NUM 
PRINT  "Column  number  «";NUM2 

Output 

Row  count  *  1 
Column  number  *  1 
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NUM$ 


The  NUM$  function  evaluates  a  numeric  expression  and  returns  a  string 
of  characters  in  PRINT  statement  format,  with  leading  and  trailing  spaces. 


Format 

str-var  =  HUMS  (num-exp) 


Syntax  Rules 

None. 


Remarks 


1.  If  num-exp  is  positive,  the  first  character  in  the  string  expression  is  a 
space.  If  num-exp  is  negative,  the  first  character  is  a  minus  sign  (-). 

2.  The  NUM$  function  does  not  include  trailing  zeros  in  the  returned 
string.  If  all  digits  to  the  right  of  the  decimal  point  are  zeros,  NUM$ 
omits  the  decimal  point  as  well. 

3.  When  num-exp  is  a  floating-point  variable  and  has  an  integer  portion 
of  six  decimal  digits  or  less  (for  example,  1234.567),  BASIC-PLUS-2 
rounds  the  number  to  six  digits  (1234.57).  If  num-exp  has  seven 
decimal  digits  or  more,  BASIC-PLUS-2  rounds  the  number  to  six  digits 
and  prints  it  in  E-format. 

4.  When  num-exp  is  between  0.1  and  1  and  contains  more  than  6  digits, 
BASIC-PLUS-2  rounds  it  to  six  digits.  When  num-exp  is  smaller  than 
0.1,  BASIC-PLUS-2  rounds  it  to  6  digits  and  prints  it  in  E-format. 

5.  The  NUM$  function  returns  a  maximum  number  of  digits  as  follows: 

•  Three  digits  for  BYTE  integers 

•  Five  digits  for  SINGLE  floating-point  numbers  and  WORD  integers 

•  Ten  digits  for  LONG  integers 

•  Sixteen  digits  for  DOUBLE  floating-point  numbers 

6.  The  last  character  in  the  returned  string  is  a  space. 
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MUM$ 


Exaaple 


10  DECLARE  STRING  number 

number  »  NUM$( 34. 5500/3 1.8) 
PRINT  number 

Output 

1.08648 
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NUM1$ 


The  NUM1$  function  changes  a  numeric  expression  to  a  numeric  character 
string  without  leading  and  trailing  spaces  and  without  rounding. 


Format 

str-var  =  ti\iM\$(num-exp} 


Syntax  Rules 

None. 


Remarks 


1.  The  NUM1$  function  returns  a  string  consisting  of  numeric  characters 
and  a  decimal  point  that  corresponds  to  the  value  of  num~exp.  Leading 
and  trailing  spaces  are  not  included  in  the  returned  string. 

2.  The  NUM1$  function  returns  a  maximum  number  of  digits  as  follows: 

•  Three  digits  for  BYTE  integers 

•  Five  digits  for  SINGLE  floating-point  numbers  and  WORD  integers 

•  Ten  digits  for  LONG  integers 

•  Sixteen  digits  for  DOUBLE  floating-point  numbers 

3.  The  NUM1$  function  does  not  produce  E  notation. 
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NUM1$ 


Example 


10  DECLARE  STRING  number 
number  >  NUMl$(PI/2) 
PRINT  number 

Output 

1.6708 
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Oni  ERROR  GO  BACK 


If  the  ON  ERROR  GO  BACK  statement  is  located  in  a  subprogram  or  DEF 
function,  it  transfers  control  to  the  calling  program  when  an  error  occurs. 
If  the  ON  ERROR  GO  BACK  statement  is  located  in  a  main  program 
module,  it  transfers  control  to  the  BASIC-PLUS-2  default  error  handler 
when  an  error  occurs. 


Format 


Syntax  Rules 


None. 


Remarks 


1.  If  there  is  no  error  outstanding,  execution  of  an  ON  ERROR  GO  BACK 
statement  causes  subsequent  errors  to  return  control  to  the  calling 
program's  error  handler. 

2.  If  there  is  an  error  outstanding,  execution  of  an  ON  ERROR  GO  BACK 
statement  immediately  transfers  control  to  the  calling  program's  error 
handler. 

3.  By  default,  DEF  functions  and  subprograms  re-signal  errors  to  the 
calling  program. 

4.  The  ON  ERROR  GO  BACK  statement  remains  in  effect  until  the 
program  unit  completes  execution  or  until  BASIC-PLUS-2  executes 
another  ON  ERROR  statement. 

5.  An  ON  ERROR  GO  BACK  statement  executed  in  the  main  program  is 
equivalent  to  an  ON  ERROR  GOTO  0  statement. 
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ON  ERROR  GO  BACK 


6.  If  a  main  program  calls  a  subprogram  named  SUBl,  and  SUBl  calls 
,the  subprogram  named  SUB2,  an  ON  ERROR  GO  BACK  statement 
executed  in  SUB2  transfers  control  to  SUBl's  error  handler  when 
an  error  occurs  in  SUB2.  If  SUBl  also  has  executed  an  ON  ERROR 
GO  BACK  statement,  BASIC-PLUS-2  transfers  control  to  the  main 
program's  error  handling  routine. 


Example 


10  IF  ERR  »  11 
THEN 

RESUME  err .hand 

ELSE 

ON  ERROR  GO  BACK 

END  IF 
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ON  ERROR  GOTO 


The  ON  ERROR  GOTO  statement  transfers  program  control  to  a  specified 
line  or  label  in  the  current  program  unit  when  a  trappable  error  occurs. 


Format 


r  ONERROR  1  r  GO  TO  1 
I  ON  ERROR  J  1  GOTO  / 


target 


Syntax  Rules 


1.  Target  must  be  a  valid  BASIC-PLUS-2  line  number  or  label  and  must 
exist  in  the  same  program  unit  as  the  ON  ERROR  GOTO  statement. 

2.  If  an  ON  ERROR  GOTO  statement  is  in  a  DEE  function,  target  must 
also  be  in  that  function  definition. 


Remarks 


1.  Execution  of  an  ON  ERROR  GOTO  statement  causes  subsequent 
errors  to  transfer  control  to  the  specified  target. 

2.  The  ON  ERROR  GOTO  statement  remains  in  effect  until  the  program 
unit  completes  execution  or  until  BASIC-PLUS-2  executes  another 
ON  ERROR  statement. 

3.  BASIC-PLUS-2  does  not  allow  recursive  error  handling.  If  a  second 
error  occurs  during  execution  of  an  error-handling  routine,  control 
passes  to  the  BASIC-PLUS-2  error  handler  and  the  program  stops 
executing. 
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ON  ERROR  GOTO 


Example 


50  SUB  LIST  (STRING  A) 

DECLARE  STRING  B 
ON  ERROR  GOTO  err.block 
OPEN  A  FOR  INPUT  AS  FILE  #1 

Input .loop : 

LINPUT  #1,  B 
PRINT  B 


GOTO  Input.loop 

err.block : 

IF  (ERR*11%) 

THEN 

CLOSE  »1% 

RESUME  done 
ELSE 

ON  ERROR  GOTO  0 
END  IF 


done: 
END  SUB 
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ON  ERROR  GOTO  0 


The  ON  ERROR  GOTO  0  statement  disables  ON  ERROR  error  handling 
and  passes  control  to  the  BASIC-PLUS-2  error  handler  when  an  error 
occurs. 


Format 

r  ON  ERROR  1/  GO  TO  In 
I  ONERROR  J  1  GOTO  J 


Syntax  Rules 

None. 


Remarks 


1.  If  an  error  is  outstanding,  execution  of  an  ON  ERROR  GOTO  0 
statement  immediately  transfers  control  to  the  BASIC-PLUS-2  error 
handler.  The  BASIC-PLUS-2  error  handler  will  report  the  error  and 
exit  the  program. 

2.  If  there  is  no  error  outstanding,  execution  of  an  ON  ERROR  GOTO  0 
statement  causes  subsequent  errors  to  transfer  control  to  the 
BASIC-PLUS-2  error  handler. 
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ON  ERROR  GOTOO 


Example 


10  ON  ERROR  GOTO  err.routlne 
FOR  I  -  1%  TO  lOX 

PRINT  "Please  type  a  number" 
INPUT  A 
NEXT  I 
err.routlne : 

IF  ERR  «  50 
THEN 

RESUME 

ELSE 

ON  ERROR  GOTO  0 

END  IF 

Output 


Please  type  a  number 
?  ICTRL/Zl 

?End  of  file  on  device  at  line  10  In  "MYPROG  " 
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ON  . . .  GOSUB 


The  ON  . .  .  GOSUB  statement  transfers  program  control  to  one  of  several 
subroutines,  depending  on  the  value  of  a  control  expression. 


Format 

ON  int-exp  GOSUB  target,  . . .  /OTHERWISE  target ] 


Syntax  Rules 


1.  Int-exp  determines  which  target  BASlC-PLUS-2  selects  as  the  GOSUB 
argument.  If  int-exp  equals  1,  BASIC-PLUS-2  selects  the  first  target.  If 
int-exp  equals  2,  BASIC-PLUS-2  selects  the  second  target,  and  so  on. 

2.  Target  must  be  a  valid  BASIC-PLUS-2  line  number  or  label  and  must 
exist  in  the  current  program  unit. 


Remarks 


1.  Control  cannot  be  transferred  into  a  statement  block  (such  as  FOR  . .  . 
NEXT,  UNTIL  .  .  .  NEXT,  WHILE  .  .  .  NEXT,  DEF  .  .  .  END  DEF,  or 
SELECT  .  . .  END  SELECT). 

2.  If  there  is  an  OTHERWISE  clause,  and  if  int-exp  is  less  than  1  or 
greater  than  the  number  of  targets  in  the  list,  BASIC-PLUS-2  selects 
the  target  of  the  OTHERWISE  clause. 

3.  If  there  is  no  OTHERWISE  clause,  and  if  int-exp  is  less  than  1  or 
greater  than  the  number  of  targets  in  the  list,  BASIC-PLUS-2  signals 
the  error  ‘ON  statement  out  of  range"  (ERR=58). 

4.  If  a  target  specifies  a  nonexecutable  statement,  BASIC-PLUS-2  trans¬ 
fers  control  to  the  first  executable  statement  that  lexically  follows  the 
target. 
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Example 


100  INPUT  "Please  enter  1,  2  or  3";  AV, 

ON  Ay,  GOSUB  1000  ,  2000  ,  3000,  OTHERWISE  err.routine 
GOTO  done 

1000  PRINT  "That  was  a  1" 

RETURN 

2000  PRINT  "That  was  a  2" 

RETURN 

3000  PRINT  "That  was  a  3" 

RETURN 

err_routine : 

PRINT  "Out  of  range: 

GOTO  100 
done: 

END 
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oni  . . .  GOTO 


The  ON  .  .  .  GOTO  statement  transfers  program  control  to  one  of  several 
lines  or  targets,  depending  on  the  value  of  a  control  expression. 


Format 

ON  int-exp  (  ® J J®  |  target,  . . .  /"OTHERWISE  target ] 


Syntax  Rules 


1.  Int~exp  determines  which  target  BASIC-PLUS-2  selects  as  the  GOTO 
argument.  If  int-exp  equals  1,  BASIC-PLUS-2  selects  the  first  target.  If 
int-exp  equals  2,  BASIC-PLUS-2  selects  the  second  target,  and  so  on. 

2.  Target  must  be  a  valid  BASIC-PLUS-2  line  number  or  a  label  and  must 
exist  in  the  current  program  unit. 


Remarks 


1.  Control  cannot  be  transferred  into  a  statement  block  (such  as  FOR  . .  . 
NEXT,  UNTIL  .  .  .  NEXT,  WHILE  .  .  .  NEXT,  DEF  .  .  .  END  DEF,  or 
SELECT  .  .  .  END  SELECT). 

2.  If  there  is  an  OTHERWISE  clause,  and  if  int-exp  is  less  than  1  or 
greater  than  the  number  of  targets  in  the  list,  BASIC-PLUS-2  transfers 
control  to  the  target  of  the  OTHERWISE  clause. 

3.  If  there  is  no  OTHERWISE  clause,  and  if  int-exp  is  less  than  1  or 
greater  than  the  number  of  line  numbers  in  the  list,  BASIC-PLUS-2 
signals  "ON  statement  out  of  range"  (ERR=58). 

4.  If  a  target  specifies  a  nonexecutable  statement,  BASIC-PLUS-2  trans¬ 
fers  control  to  the  first  executable  statement  that  lexically  follows  the 
target. 
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Example 


10  ON  INDEXX  GOTO  700,800,900  OTHERWISE  1000 
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OniECHR 


The  ONECHR  function  allows  single-character  input  (ODT  submode)  to 
a  terminal  opened  on  a  specified  channel.  This  function  must  be  used  in 
conjunction  with  the  GET  statement. 


Format 

int-vbl = OfiECHRfchnl-exp) 


Syntax  Rules 


1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  an  open  terminal.  It  cannot  be  preceded  by  a  number 
sign  (#). 

2.  The  ONECHR  function  must  be  used  immediately  before  a  GET 
statement. 


Remarks 


1.  BASIC  disables  the  ONECHR  function  immediately  after  a  GET  state¬ 
ment  executes.  Therefore,  your  program  must  invoke  the  ONECHR 
function  for  each  single  character  input  you  want  to  perform. 

2.  Control  passes  to  the  program  as  soon  as  you  enter  a  character.  You 
do  not  have  to  type  a  line  terminator. 

3.  To  obtain  optimal  performance  (especially  when  using  scrolling 
regions  and  other  complicated  operations),  it  is  necessary  that  you 
attach  to  the  terminal  before  using  the  ONECHR  function.  To  attach 
to  the  terminal  use  an  lO.ATT  QIO.  See  your  operating  system 
documentation  for  additional  information  about  QIOs. 
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Example 


100  OPEN  "TI:"  FOR  INPUT  AS  FILE  #1X 
n  •  ONECHR (IX) 

GET  «1X 

HOVE  FROM  fix.  A«  °  IX 
PRINT  At 
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OPEN 


The  OPEN  statement  opens  a  file  for  processing.  It  transfers  user-specified 
file  characteristics  to  Record  Management  Services  (RMS),  or  to  the 
operating  system  on  RSTS/E  systems,  and  verifies  the  results. 


Format 

OPEN  file-spec 


FOR  INPUT 
FOR  OUTPUT 

[,  open-clause  ]  . . . 

open-clause: 


ACCESS 


AS[f\L£][#]chnl-exp 


APPEND 

READ 

WRITE 

► 

MODIFY 

1  SCRATCH 

NONE  ] 

READ 

WRITE 

MODIFY  J 

ALLOW 


[  BUFFER  int-exp  ] 

[  CLUSTERSIZE  int-exp  ] 
[CONTIGUOUS  ] 

[  DEFAULTNAME  file-spec  ] 
[  EXTENDSIZE  int-exp  1 
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[  FILESIZE  int-exp  1 


[  MAP  map-name  ] 


[  ORGANIZATION  ]  ^ 


INDEXED 
RELATIVE 
SEQUENTIAL  ^ 
UNDEFINED 
VIRTUAL 


FIXED 
STREAM 
.  VARIABLE 


[  RECORDSIZE  int-exp  1 


■ 

ANY  1 

RECORDTYPE 

FORTRAN 

LIST 

► 

NONE 

[TEMPORARY  ] 

[  USEROPEN  func-name  ] 
[  WINDOWSIZE  int-exp  ] 


Indexed  files  only: 


[  ALTERNATE  [  KEY  ]  key-clause  [  DUPLICATES  ]  [  CHANGES  ]  ] 
[  PRIMARY  [  KEY  ]  key-clause  [  DUPLICATES  ]  ] 

Relative  and  indexed  files  only: 

[  BUCKETSIZE  int-exp  ] 

1  CONNECT  chnl-exp2  ] 
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Sequential  files  only: 

[  BLOCKSIZE  int-exp  ] 

[  NOREWIND  ] 

[  [N0]SPAN  ] 

Virtual  files  only: 

[  MODE  int-exp  ] 


key-clause: 


{int-unsubs-m 
decimal-unsubs-var 
str-unsubs-var 

(str-unsubs-varl ,  . . .  str-unsubs-var8}  > 


Syntax  Rules 


1.  File-spec  specifies  the  file  to  be  opened  and  associated  with 
chnl-exp.  It  can  be  any  valid  string  expression  and  must  be  a  valid 
file  specification.  BASIC-PLUS-2  passes  these  values  to  RMS  without 
editing,  alteration,  or  validity  checks. 

2.  BASIC-PLUS-2  supplies  SY:  as  the  default  device  if  you  do  not 
specify  a  device  in  your  file  specification.  No  default  file  type  is 
supplied  unless  you  include  the  DEFAULTNAME  clause  in  the  OPEN 
statement. 

3.  The  FOR  clause  determines  how  BASIC-PLUS-2  opens  a  file. 

•  If  you  open  a  file  with  FOR  INPUT,  the  file  must  exist  or 
BASIC-PLUS-2  signals  an  error. 

•  If  you  open  a  file  with  FOR  OUTPUT,  BASIC-PLUS-2  creates  the 
file  if  it  does  not  exist.  On  RSX  systems,  if  the  file  exists, 
BASIC-PLUS-2  creates  a  new  version  of  the  file;  On  RSTS/E 
systems,  BASIC-PLUS-2  overwrites  the  file. 

•  If  you  do  not  specify  either  FOR  INPUT  or  FOR  OUTPUT, 
BASIC-PLUS-2  tries  to  open  an  existing  file.  If  there  is  no  such 
file,  BASIC -PLUS-2  creates  one. 
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4.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number  to 
be  associated  with  the  file  being  opened.  It  can  be  preceded  by  an 
optional  number  sign  (# )  and  must  be  in  the  range  of  1  through  12. 

5.  A  statement  that  accesses  a  file  cannot  execute  until  you  open  that  file 
and  associate  it  with  a  channel. 


Remarks 


1.  The  OPEN  statement  does  not  retrieve  records. 

2.  Channel  #0,  the  terminal,  is  always  open.  If  you  try  to  open  channel 
zero,  BASIC-PLUS-2  signals  the  error  "I/O  channel  already  open" 
(ERR=7). 

3.  If  a  program  opens  a  file  on  a  channel  already  associated  with  an  open 
file,  BASIC -PLUS-2  closes  the  previously  opened  file  and  opens  the 
new  one. 

4.  The  implicit  or  explicit  closing  of  a  file  will  render  any  channels 
connected  to  that  file  invalid. 

5.  The  ACCESS  clause  determines  how  the  program  can  use  the  file. 

•  ACCESS  READ  allows  only  FIND,  GET,  or  other  input  statements 
on  the  file.  The  OPEN  statement  cannot  create  a  file  if  the 
ACCESS  READ  clause  is  specified. 

•  ACCESS  WRITE  allows  only  PUT,  UPDATE,  or  other  output 
statements  on  the  file. 

•  ACCESS  MODIFY  allows  any  I/O  statement  except  SCRATCH  on 
the  file.  ACCESS  MODIFY  is  the  default. 

•  ACCESS  SCRATCH  allows  any  I/O  statement  valid  for  a  sequen¬ 
tial  or  terminal-format  file. 

•  ACCESS  APPEND  is  the  same  as  ACCESS  WRITE  for  sequential 
files,  except  that  BASIC-PLUS-2  positions  the  file  pointer  after 
the  last  record  when  it  opens  the  file.  You  cannot  use  ACCESS 
APPEND  on  relative  or  indexed  files. 

6.  The  ALLOW  clause  can  be  used  in  the  OPEN  statement  to  specify  file 
sharing  of  relative,  indexed,  sequential,  and  virtual  files. 

•  ALLOW  NONE  lets  no  other  users  access  the  file.  This  is  the 
default  if  any  access  other  than  READ  is  specified.  Note  that  you 
must  have  write  access  to  the  file  in  order  to  specify  ALLOW 
NONE. 
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•  ALLOW  READ  lets  other  users  have  read  access  to  the  file. 

•  ALLOW  WRITE  lets  other  users  have  write  access  to  the  file. 

•  ALLOW  MODIFY  lets  other  users  have  unlimited  access  to  the 
file. 

7.  The  BLOCKSIZE  clause  specifies  the  physical  block  size  of  magnetic 
tape  files.  The  BLOCKSIZE  clause  can  be  used  for  magnetic  tape  files 
only. 

•  The  value  of  int~exp  is  the  number  of  records  in  a  block. 
Therefore,  the  block  size  in  bytes  is  the  product  of  the 
RECORDSIZE  and  the  BLOCKSIZE  value. 

•  The  default  blocksize  is  one  record. 

8.  The  BUCKETSIZE  clause  applies  only  to  relative  and  indexed  files.  It 
specifies  the  size  of  an  RMS  bucket  in  terms  of  the  number  of  records 
one  bucket  should  hold. 

•  The  value  of  int-exp  determines  the  number  of  records  in  a  bucket. 
Therefore,  the  BUCKETSIZE  in  bytes  is  the  product  of  the  record 
size  and  bucket  size. 

•  The  default  is  one  record. 

9.  The  BUFFER  clause  can  be  used  with  all  file  organizations  except 
UNDEFINED. 

•  For  RELATIVE  and  INDEXED  files,  int~exp  specifies  the  number  of 
device  or  file  buffers  RMS  uses  for  file  processing. 

•  For  SEQUENTIAL  files,  int~exp  specifies  the  size  of  the  buffer;  for 
example,  BUFFER  8  for  a  SEQUENTIAL  file  sets  the  buffer  size  to 
eight  512-byte  blocks. 

•  For  VIRTUAL  files,  the  BUFFER  clause  has  no  effect. 

10.  The  CLUSTERSIZE  clause  allows  you  to  specify  the  smallest  amount 
of  contiguous  disk  space  to  be  allocated  when  an  RMS  or  RSTS/E 
file's  present  allocation  is  exhausted. 

•  The  CLUSTERSIZE  clause  is  valid  on  RSTS/E  systems  only.  On 
RSX  systems,  the  EXTENDSIZE  clause  serves  a  function  similar  to 
that  of  the  CLUSTERSIZE  clause. 

•  Int-exp  must  be  a  power  of  2.  For  example,  a  CLUSTERSIZE 
of  8  means  that  each  time  the  file  requires  more  disk  space,  the 
RSTS/E  operating  system  must  have  at  least  eight  contiguous 
blocks  to  allocate.  If  the  disk  is  fragmented,  therefore,  there  can 
be  no  8-block  clusters  and  BASIC-PLUS-2  signals  the  error  "No 
room  for  user  on  device"  (ERR=4). 
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•  The  default  CLUSTERSIZE  is  determined  when  the  disk  pack  is 
initialized  or  mounted.  You  can  use  the  DCL  command  SHOW 
DISK  to  determine  the  default  clustersize. 

11.  The  CONTIGUOUS  clause  causes  RMS  to  try  to  create  the  file  as  a 
contiguous  sequence  of  disk  blocks. 

•  The  CONTIGUOUS  clause  does  not  affect  existing  files  or  nondisk 
files. 

•  If  you  specify  a  CONTIGUOUS  clause  and  there  is  not  enough 
contiguous  disk  space  available,  RMS  signals  an  error. 

•  On  RSTS/E  systems,  you  cannot  extend  a  contiguous  file  beyond 
its  initially  allocated  size.  If  you  attempt  to  do  so, 

BASIC-PLUS-2  signals  the  error  "Protection  violation"  (ERR=10). 
Use  the  FILESIZE  clause  with  the  CONTIGUOUS  clause  to 
allocate  enough  contiguous  disk  space  when  you  open  the  file. 

12.  The  CONNECT  clause  establishes  additional  record  access  streams 
for  RMS  files  that  allow  your  program  to  process  more  than  one  record 
of  a  file  at  the  same  time.  Each  stream  represents  an  independent  and 
concurrently  active  sequence  of  record  operations. 

•  The  CONNECT  clause  must  specify  a  RELATIVE  or  INDEXED  file 
already  opened  on  chnl-exp2  with  the  primary  OPEN  statement. 

•  Each  connection  established  in  a  secondary  OPEN  statement  uses 
another  I/O  channel.  Because  there  are  12  available  I/O  channels, 
you  can  have  a  maximum  of  1 1  connections  to  a  file. 

•  All  clauses  in  the  secondary  OPEN  statements  must  be  identical 
except  the  MAP,  CONNECT,  and  USEROPEN  clauses. 

•  BASIC-PLUS-2  signals  the  error  "Invalid  file  options"  (ERR=139) 
if  your  program  attempts  to  connect  to  a  record  stream  that  is 
already  connected  to  another  stream. 

•  When  a  file  is  closed,  all  files  that  are  connected  to  that  file  must 
also  be  closed. 

13.  The  DEFAULTNAME  clause  lets  you  supply  a  default  file  specifica¬ 
tion. 

•  The  DEFAULTNAME  clause  is  valid  for  RMS  files  only. 

•  If  file-spec  is  not  a  complete  file  specification,  file-sped  specified 
in  the  DEFAULTNAME  clause  supplies  the  missing  parts.  For 
example: 
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10  INPUT  'FILE  NAME': Inaml 

20  OPEN  fnamO  FOB  INPUT  AS  FILE  #1%,  tt 

ORGANIZATION  SEQUENTIAL  A 
DEFAULTNAME  ''DU1:.DAT'' 

Here,  if  you  type  "ABC"  for  the  file  name,  BASIC-PLUS-2  tries  to 
open  DU1:[123,2]ABC.DAT. 

14.  The  EXTENDSIZE  clause  lets  you  specify  the  increment  by  which 
RMS  extends  a  file  after  its  initial  allocation  is  filled. 

•  The  EXTENDSIZE  clause  is  valid  on  RSX  systems  only.  On 
RSTS/E  systems,  the  CLUSTERSIZE  clause  serves  a  similar 
function  to  the  EXTENDSIZE  clause. 

•  The  value  of  int-exp  is  in  512-byte  disk  blocks. 

•  The  EXTENDSIZE  clause  has  no  effect  on  an  existing  file. 

15.  The  FILESIZE  clause  lets  you  pre-extend  a  new  file  to  a  specified  size. 

•  The  value  of  int-exp  is  the  initial  allocation  of  disk  blocks. 

•  The  FILESIZE  clause  has  no  effect  on  an  existing  file. 

16.  The  MAP  clause  specifies  that  a  previously  declared  map  is  associated 
with  the  file's  record  buffer.  The  MAP  clause  determines  the  record 
buffer's  address  and  length  unless  overridden  by  the  RECORDSIZE 
clause. 

•  The  size  of  the  specified  map  must  be  as  large  or  larger  than  the 
longest  record  length  or  maximum  record  size.  For  files  with  a 
fixed  record  size,  the  specified  map  must  match  exactly. 

•  The  size  of  the  largest  MAP  with  the  same  map  name  in  the 
current  program  unit  becomes  the  file's  record  size  if  the  OPEN 
statement  does  not  include  a  RECORDSIZE  clause. 

•  It  is  recommended  that  you  do  not  use  both  the  MAP  and 
RECORDSIZE  clauses  in  an  OPEN  statement.  If  you  do  use 
both  the  MAP  and  RECORDSIZE  clauses  in  an  OPEN  statement, 
the  following  rules  apply: 

~  The  RECORDSIZE  clause  overrides  the  record  size  set  by  the 
MAP  clause. 

—  The  map  must  be  as  large  or  larger  than  the  specified 
RECORDSIZE. 

•  If  there  is  no  MAP  clause,  the  record  buffer  space  that 
BASIC-PLUS-2  allocates  is  not  directly  accessible.  Therefore, 
MOVE  statements  are  needed  to  access  data  in  the  record  buffer. 
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•  You  must  have  a  MAP  clause  when  creating  an  indexed  file;  you 
cannot  use  KEY  clauses  without  MAP  statements  because  keys 
serve  as  offsets  into  the  buffer. 

17.  The  MODE  clause  is  provided  for  non-RMS  file  operations. 

•  Int-exp  specifies  a  MODE  value. 

•  On  RSX  systems,  MODE  is  ignored  except  when  your  program 
is  doing  device-specific  I/O  to  a  magnetic  tape.  In  this  case,  you 
can  use  MODE  to  set  the  tape  density.  In  all  other  cases,  RSX 
ignores  the  MODE  value.  See  the  BASIC-PLUS-2  User's  Guide  for 
information  on  MODE  values. 

•  On  RSTS/E  systems,  MODE  values  affect  only  native  RSTS/E 
files,  not  RMS  files.  MODE  values  have  different  meanings 
depending  on  the  context  in  which  you  use  them.  This  is  because 
other  pieces  of  software  can  scan  the  MODE  values  to  see  which 
bits  are  set.  For  example,  bit  14  may  have  one  meaning  to  the 
RSTS/E  terminal  driver  but  another  meaning  to  the  file  processor. 
See  the  BASIC-PLUS-2  User's  Guide  for  information  on  MODE 
values. 

18.  The  NOREWIND  clause  controls  tape  positioning  on  magnetic  tape 
files  so  that  the  operating  system  does  not  position  the  tape  at  its 
beginning.  Your  program  can  then  search  for  records  from  the  current 
position. 

•  When  you  specify  NOREWIND  with  an  OPEN  FOR  INPUT 
statement,  BASIC -PLUS-2  instructs  the  system  to  search  for  the 
specified  file  without  rewinding.  If  the  file  is  not  found, 
BASIC-PLUS-2  instructs  the  system  to  rewind  the  tape  and  search 
for  the  file  from  the  start  of  the  tape.  If  the  file  is  still  not  found, 
BASIC-PLUS-2  signals  the  error  "File  not  found." 

•  If  you  specify  NOREWIND  with  an  OPEN  FOR  OUTPUT  state¬ 
ment,  BASIC-PLUS-2  instructs  the  system  to  position  the  tape  at 
its  logical  end.  The  program  can  then  write  records. 

•  By  default,  if  you  do  not  specify  NOREWIND,  the  tape  is  posi¬ 
tioned  at  its  beginning. 

•  The  NOREWIND  clause  can  be  used  for  magnetic  tape  files  only. 

19.  The  NOSPAN  clause  specifies  that  records  cannot  cross  block  bound¬ 
aries.  The  NOSPAN  clause  does  not  affect  nondisk  files.  The 
SPAN  clause  specifies  that  sequential  records  can  cross  block  bound¬ 
aries.  SPAN  is  the  default. 
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20.  The  ORGANIZATION  clause  specifies  the  organization  of  a  file. 
When  present,  it  must  precede  all  other  clauses.  When  you  specify 
an  ORGANIZATION  clause,  you  must  also  specify  one  of  the  follow¬ 
ing  organization  options:  UNDEFINED,  INDEXED,  SEQUENTIAL, 
RELATIVE,  or  VIRTUAL. 

•  Specify  ORGANIZATION  UNDEFINED  if  you  do  not  know 
the  actual  organization  of  the  file.  When  you  specify  the 
ORGANIZATION  UNDEFINED  clause,  a  block  I/O  file  is  opened. 
You  can  then  use  the  FSP$  function  or  a  USEROPEN  routine 

to  determine  the  attributes  of  the  file.  You  will  usually  want  to 
specify  the  RECORDTYPE  ANY  clause  with  the  ORGANIZATION 
UNDEFINED  clause.  The  combination  of  these  two  clauses  should 
allow  you  to  access  any  file  sequentially.  You  must  have  exclu¬ 
sive  access  to  a  file  in  order  to  specify  the  ORGANIZATION 
UNDEFINED  clause  in  an  OPEN  statement.  Therefore,  you 
must  also  specify  the  ALLOW  NONE  clause  when  you  specify 
ORGANIZATION  UNDEFINED. 

•  When  you  specify  ORGANIZATION  INDEXED,  you  create  an 
indexed  file  that  contains  data  records  that  are  sorted  in  ascending 
or  descending  order  according  to  a  primary  index  key  value.  You 
can  access  an  existing  file  with  descending  keys;  however,  you 
cannot  create  a  file  with  descending  keys. 

—  The  index  keys  you  specify  determine  the  order  in  which 
records  are  stored. 

—  Index  keys  must  be  variables  declared  in  a  MAP  statement 
associated  with  the  OPEN  statement  for  the  file. 

—  BASIC-PLUS-2  allows  you  to  specify  an  indexed  file  as  either 
variable  or  fixed  length. 

•  When  you  specify  ORGANIZATION  SEQUENTIAL,  you  create  a 
file  that  stores  records  in  the  order  in  which  they  are  written. 

“  Sequential  files  can  contain  records  of  any  valid 

BASIC-PLUS-2  record  format:  fixed-length,  variable-length, 
or  stream.  If  you  do  not  specify  a  record  format  with  the 
ORGANIZATION  SEQUENTIAL  clause,  the  default  is 
variable-length  records. 

—  If  you  open  an  existing  file  using  stream  as  a  record  format 
option,  the  STREAM  records  can  be  delimited  by  any  special 
character. 
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•  When  you  specify  ORGANIZATION  RELATIVE,  you  create  a 
file  that  contains  a  series  of  records  that  are  numbered  consecu¬ 
tively.  BASIC-PLUS-2  allows  you  to  specify  either  fixed-length  or 
variable-length  records. 

•  When  you  specify  ORGANIZATION  VIRTUAL,  you  create  a 
sequentially  fixed  file  with  a  record  size  of  512  (or  a  multiple  of 
512).  You  can  then  access  the  file  with  the  FIND,  GET,  PUT, 
or  UPDATE  statements  or  through  one  or  more  virtual  arrays. 
BASIC-PLUS-2  allows  you  to  overwrite  existing  records  in  a  file 
not  containing  virtual  arrays  and  opened  as  ORGANIZATION 
VIRTUAL  by  using  the  PUT  statement  with  a  RECORD  clause. 

All  other  organizations  require  the  UPDATE  statement  to  change 
an  existing  record.  It  is  recommended  that  you  also  use  the 
UPDATE  statement  to  change  existing  records  in  VIRTUAL  files 
that  do  not  contain  virtual  arrays. 

•  If  you  omit  the  ORGANIZATION  clause,  BASIC-PLUS-2  opens  a 
terminal-format  file. 

—  Terminal-format  files  are  implemented  as  RMS  sequential 
variable  files  on  RSX  systems  and  store  ASCII  characters  in 
variable-length  records. 

—  Carriage  control  is  performed  by  the  operating  system;  and  on 
RSX  systems,  the  record  does  not  contain  carriage  returns  or 
line  feeds.  RSTS/E  terminal-format  files,  however,  do  contain 
carriage  return  and  line  feed  characters. 

—  You  use  essentially  the  same  syntax  to  access  terminal-format 
files  as  when  reading  from  or  writing  to  the  terminal  (INPUT 
and  PRINT). 

21.  The  PRIMARY  KEY  clause  lets  you  specify  an  indexed  file's  key. 
You  must  specify  a  primary  key  when  opening  an  indexed  file.  The 
ALTERNATE  KEY  clause  lets  you  specify  up  to  254  alternate  keys. 
The  ALTERNATE  KEY  clause  is  optional. 

•  RMS  creates  one  index  list  for  each  primary  and  alternate  key  you 
specify.  These  indexes  are  part  of  the  file  and  contain  pointers  to 
the  records.  Each  key  you  specify  corresponds  to  a  sorted  list  of 
record  pointers. 

•  The  keys  you  specify  determine  the  order  in  which  records  in  the 
file  are  stored.  All  keys  must  be  variables  declared  in  the  file's 
corresponding  MAP  statement.  The  position  of  the  key  in  the 
MAP  statement  determines  its  position  in  the  record.  The  data 
type  and  size  of  the  key  are  as  declared  in  the  MAP  statement. 

•  A  key  can  be  an  unsubscripted  string  or  WORD  variable. 
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•  You  can  also  create  a  segmented  index  key  for  string  keys  by 
separating  the  string  variable  names  with  commas  and  enclosing 
them  in  parentheses.  You  can  then  reference  a  segment  of  the 
specified  key  by  referencing  one  of  the  string  variables  instead  of 
the  entire  key.  A  string  key  can  have  up  to  eight  segments. 

•  The  order  of  appearance  of  keys  determines  key  numbers.  The 
primary  key,  which  must  appear  first,  is  key  #0.  The  first  alternate 
key  is  #1,  and  so  on. 

•  DUPLICATES  in  the  PRIMARY  and  ALTERNATE  key  clauses 
specifies  that  two  or  more  records  can  have  the  same  key  value.  If 
you  do  not  specify  DUPLICATES,  the  key  value  must  be  unique 
in  all  records. 

•  CHANGES  in  the  ALTERNATE  KEY  clause  specifies  that  you  can 
change  the  value  of  an  alternate  key  when  updating  records.  If 
you  do  not  specify  CHANGES  when  creating  the  file,  you  cannot 
change  the  value  of  a  key.  If  you  specify  the  CHANGES  clause, 
you  must  also  specify  the  duplicates  clause.  You  cannot  specify 
CHANGES  with  the  PRIMARY  KEY  clause. 

•  ALTERNATE  KEY  clauses  are  optional  for  existing  files.  If  you  do 
specify  a  key,  it  must  match  a  key  in  the  file. 

22.  The  RECORDTYPE  clause  specifies  the  file's  record  attributes.  The 
RECORDTYPE  clause  can  only  be  used  with  RMS  files. 

•  ANY  specifies  a  match  with  any  file  attributes  when  opening  an 
existing  file.  If  you  create  a  new  file,  ANY  is  treated  as  LIST  for 
all  organizations  except  VIRTUAL.  For  VIRTUAL,  it  is  treated  as 
NONE. 

•  FORTRAN  specifies  a  control  character  in  the  record's  first  byte. 

•  LIST  specifies  implied  carriage  control,  <CR>  <LF>  .  This  is 
the  default  for  all  file  organizations  except  VIRTUAL. 

•  NONE  specifies  no  attributes.  This  is  the  default  for  VIRTUAL 

files.  ^ 

23.  The  RECORDSIZE  clause  specifies  the  file's  record  size.  Note  that 
there  are  restrictions  on  the  maximum  record  size  allowed  for  various 
file  and  record  formats.  See  the  RMS-11  documentation  for  more 
information. 

•  For  fixed-length  records,  int-exp  specifies  the  size  of  all  records. 

•  For  variable-length  records,  int-exp  specifies  the  size  of  the  largest 
record. 
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•  It  is  recommended  that  you  do  not  use  both  the  MAP  and 
RECORDSIZE  clauses  in  an  OPEN  statement.  If  you  do  use 
both  the  MAP  and  RECORDSIZE  clauses  in  an  OPEN  statement, 
the  following  rules  apply: 

—  The  RECORDSIZE  clause  overrides  the  record  size  set  by  the 
MAP  clause. 

—  The  map  must  be  as  large  or  larger  than  the  specified 
RECORDSIZE. 

•  If  you  specify  a  MAP  clause  but  no  RECORDSIZE  clause,  the 
record  size  is  equal  to  the  map  size. 

•  If  there  is  no  MAP  clause,  the  RECORDSIZE  clause  determines 
the  record  size. 

•  When  creating  a  relative  or  indexed  file,  you  must  specify  either  a 
MAP  or  RECORDSIZE  clause;  otherwise,  BASIC-PLUS-2  signals 
an  error. 

•  For  fixed  files,  the  record  size  must  match  exactly. 

•  If  you  do  not  specify  a  RECORDSIZE  clause  when  opening  an 
existing  file,  BASIC-PLUS-2  retrieves  the  record  size  value  from 
the  file. 

•  When  you  create  SEQUENTIAL  files,  BASIC-PLUS-2  supplies  a 
default  record  size  of  132. 

•  The  record  size  is  always  512  for  VIRTUAL  files  unless  you  specify 
a  RECORDSIZE. 

24.  The  TEMPORARY  clause  causes  BASIC-PLUS-2  to  delete  the  output 

file  as  soon  as  the  program  closes  it. 

25.  The  USEROPEN  clause  lets  you  open  a  file  with  your  own 

FUNCTION  subprogram. 

•  Func-name  is  the  name  of  a  MACRO  program;  it  cannot  be  the 
name  of  a  BASIC-PLUS-2  program. 

•  You  do  not  need  to  declare  the  useropen  routine  as  an  external 
function. 

•  BASIC-PLUS-2  calls  the  user  program  after  it  fills  the  File  Access 
Block  (FAB),  the  Record  Access  Block  (RAB),  and  the  Extended 
Attribute  Blocks  (XAB)  .  The  subprogram  must  issue  the  appropri¬ 
ate  RMS  calls,  including  $OPEN  and  $CONNECT,  and  return  the 
RMS  status  as  the  value  of  the  function.  See  the  BASlC~PLUS-2 
User's  Guide  for  more  information  on  the  USEROPEN  routine. 
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26.  The  WINDOWSIZE  clause  followed  by  int-exp  lets  you  specify  the 
number  of  block  retrieval  pointers  you  want  to  maintain  in  memory 
for  the  file.  Retrieval  pointers  are  associated  with  the  file  header  and 
point  to  contiguous  blocks  on  disk.  By  keeping  retrieval  pointers  in 
memory,  you  can  reduce  the  I/O  associated  with  locating  a  record, 
as  the  operating  system  does  not  have  to  access  the  file  header  for 
pointers  as  frequently. 

•  The  number  of  retrieval  pointers  in  memory  at  any  one  time  is 
determined  by  the  system  default  or  by  the  WINDOWSIZE  clause. 

•  On  RSX  systems,  you  can  specify  up  to  127  retrieval  pointers.  The 
default  number  of  retrieval  pointers  is  seven. 

•  On  RSTS/E  systems,  the  number  of  pointers  in  a  window  block 
is  fixed  at  seven.  Thus,  you  cannot  use  the  WINDOWSIZE  clause. 
You  can,  however,  use  the  CLUSTERSIZE  clause  to  increase  the 
number  of  contiguous  blocks  mapped  by  one  retrieval  pointer. 
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Example  1 

10  OPEN  "FILE. DAT"  AS  FILE  #4 


Example  2 


10  OPEN  "INPUT.DAT"  FOR  INPUT  AS  FILE  #4, 


k 

k 

k 

k 


ORGANIZATION  SEQUENTIAL  FIXED. 
RECORDSIZE  200. 

MAP  ABC. 

ALLOW  MODIFY.  ACCESS  MODIFY 


OPEN  Newlilel  FOR  OUTPUT  AS  FILE  #3. 

INDEXED  VARIABLE. 

MAP  Emp.name. 

DEFAULTNAME  "SYi.DAT". 

PRIMARY  KEY  Last!  DUPLICATES. 

ALTERNATE  KEY  First#  DUPLICATES.  CHANGES 


k 

k 

k 

k 

k 


MAP  (SEGKEY)  STRING  last.name  *  15. 

MI  *  1,  first.name  *  15 


k 


OPEN  "NAMES. IND"  FOR  OUTPUT  AS  FILE  #1. 
ORGANIZATION  INDEXED. 

PRIMARY  KEY  (last.name.  first.name.  MI). 
MAP  SEGKEY 


k 

k 

k 
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OPTION 

The  OPTION  statement  allows  you  to  set  compilation  qualifiers  such  as 
default  data  type,  size,  and  scale  factor.  You  can  also  set  compilation 
conditions  such  as  constant  type  checking.  The  options  you  set  affect  only 
the  program  module  in  which  the  OPTION  statement  occurs. 


Format 

OPTION  option-clause,  . . . 


option-clause:  < 


CONSTANT  TYPE 

VlPtPtype-clause 
S\Zf=size-clause 
^  SCM£=int-const 


=const-tYpe-clause  ' 


const-type-clause: 


REAL  \ 
INTEGER  J 


(  INTEGER 

type-clause:  ]  REAL 

I  EXPLICIT 


size-clause: 


size-item: 


(  size-item  1 

\  (size-item,  . . .  )  j 

I  INTEGER  int-clause 
\  REAL  real-clause 


int-clause: 
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BYTE 

WORD 

LONG 


real-clause:  |  SINGLE  | 

I  DOUBLE  / 


OPTION 


Syntax  Rules 

None. 


Remarks 


1.  Option-clause  specifies  the  compilation  qualifiers  to  be  in  effect  for 
the  program  module. 

2.  Const-type-clause  specifies  the  data  type  for  all  constants  that  do  not 
end  in  a  data  type  suffix  or  are  not  in  explicit  literal  notation  with  a 
data  type  supplied. 

3.  Type-clause  sets  the  default  data  type  for  variables  that  have  not 
been  explicitly  declared  and  for  constants  if  no  constant  type  clause  is 
specified.  You  can  specify  only  one  type-clause  in  a  program  module. 

4.  Size-clause  sets  the  default  data  subtypes  for  floating-point  and 
integer  data.  Size-item  specifies  the  data  subtype  you  want  to  set. 
You  can  specify  an  INTEGER  or  REAL  size-item,  or  any  combination. 
Multiple  size-items  in  an  OPTION  statement  must  be  enclosed  in 
parentheses  and  separated  by  commas. 

5.  SCALE  controls  the  scaling  of  double-precision  floating-point  vari¬ 
ables.  Int-const  specifies  the  power  of  10  you  want  as  the  scaling 
factor.  It  must  be  an  integer  between  0  and  6  or  BASIC-PLUS-2 
signals  an  error.  See  the  description  of  the  SCALE  command  in 
Chapter  2  of  this  manual  for  more  information  on  scaling. 

6.  You  can  have  more  than  one  option  in  an  OPTION  statement,  or  you 
can  use  multiple  OPTION  statements  in  a  program  module;  however, 
each  OPTION  statement  must  lexically  precede  all  other  source  code 
in  the  program  module,  with  the  exception  of  comment  fields,  REM, 
PROGRAM,  SUB,  FUNCTION,  and  OPTION  statements. 

7.  OPTION  statement  specifications  apply  only  to  the  program  module 
in  which  the  statement  appears  and  affect  all  variables  in  the  module, 
including  SUB  and  FUNCTION  parameters. 
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8.  BASIC-PLUS-2  signals  an  error  in  the  case  of  conflicting  options.  For 
example,  you  cannot  specify  more  than  one  type-clause  or  SCALE 
factor  in  the  same  program  unit. 

9.  If  you  do  not  specify  a  type-clause  or  a  subtype-clause,  BASIC-PLUS-2 
uses  the  current  environment  default  data  types. 

10.  If  you  do  not  specify  a  scale  factor,  BASIC-PLUS-2  uses  the  current 
environment  default  scale  factor. 


Example 


FUNCTION  REAL  DOUBLE  monthly_payment , 
(DOUBLE  Interest.rate . 


LONG  no.ol. payment 8, 

DOUBLE  principle) 


A 

k 

k 


OPTION  TYPE  =  REAL. 

SIZE  »  (REAL  DOUBLE.  INTEGER  LONG) 
SCALE  «  4 


k 

k 
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PLACES 

The  PLACES  function  explicitly  changes  the  precision  of  a  numeric  string. 
PLACES  returns  a  numeric  string,  truncated  or  rounded,  according  to  the 
value  of  an  integer  argument  you  supply. 


Format 

str-var=P\ACE$(str-exp,  int-exp) 


Syntax  Rules 


1.  Str-exp  specifies  the  numeric  string  you  want  to  process.  It  can  have 
ASCII  digits,  an  optional  minus  sign  ( - ),  and  an  optional  decimal 
point  ( . ). 

2.  Int-exp  specifies  the  numeric  precision  of  str-exp.  Table  4-6  shows 
examples  of  rounding  and  truncation  and  the  values  of  int-exp  that 
produce  them. 


Remarks 


1.  If  str-exp  has  more  than  60  characters,  BASIC-PLUS-2  signals  the 
error  "Illegal  number"  (ERR=52). 

2.  Str-exp  is  rounded  or  truncated,  or  both,  according  to  the  value  of 
int-exp. 

3.  If  int-exp  is  between  -60  and  60,  rounding  and  truncation  occur  as 
follows: 

•  For  positive  integer  expressions,  rounding  occurs  to  the  right  of 
the  decimal  place.  For  example,  if  int-exp  is  1,  rounding  occurs 
one  digit  to  the  right  of  the  decimal  place  (the  number  is  rounded 
to  the  nearest  tenth).  If  int-exp  is  2,  rounding  occurs  two  digits 
to  the  right  of  the  decimal  place  (the  number  is  rounded  to  the 
nearest  hundredth),  and  so  on. 

•  If  int-exp  is  zero,  BASIC-PLUS-2  rounds  to  the  nearest  unit. 
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•  For  negative  integer  expressions,  rounding  occurs  to  the  left  of  the 
decimal  point.  If  ini-exp  is  -1,  for  example,  BASIC-PLUS-2  moves 
the  decimal  point  one  place  to  the  left,  then  rounds  to  units.  If 
ini-exp  is  -2,  rounding  occurs  two  places  to  the  left  of  the  decimal 
point;  BASIC-PLUS-2  moves  the  decimal  point  two  places  to  the 
left,  then  rounds  to  tens. 

4.  If  ini-exp  is  between  9940  and  10,060,  truncation  occurs  as  follows: 

•  If  ini-exp  is  10,000,  BASIC-PLUS-2  truncates  the  number  at  the 
decimal  point. 

•  If  ini-exp  is  greater  than  10,000  (10,000  plus  n)  BASIC-PLUS-2 
truncates  the  numeric  string  n  places  to  the  right  of  the  decimal 
point.  For  example,  if  ini-exp  is  10,001  (10,000  plus  1), 
BASIC-PLUS-2  truncates  the  number  starting  one  place  to  the 
right  of  the  decimal  point.  If  ini-exp  is  10,002  (10,000  plus  2), 
BASIC-PLUS-2  truncates  the  number  starting  two  places  to  the 
right  of  the  decimal  point,  and  so  on. 

•  If  ini-exp  is  less  than  10,000  (10,000  minus  n),  BASIC-PLUS-2 
truncates  the  numeric  string  n  places  to  the  left  of  the  decimal 
point.  For  example,  if  ini-exp  is  9999  (10,000  minus  1), 
BASIC-PLUS-2  truncates  the  number  starting  one  place  to  the  left 
of  the  decimal  point.  If  9998  (10,000  minus  2),  BASIC-PLUS-2 
truncates  starting  two  places  to  the  left  of  the  decimal  point,  and 
so  on. 

5.  If  ini-exp  is  not  between  -60  and  60  or  9940  and  10,060, 
BASIC-PLUS-2  returns  a  value  of  zero. 

6.  If  you  specify  a  floating-point  expression  for  ini-exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 

7.  Table  4-6  shows  examples  of  rounding  and  truncation  and  the  values 
of  ini-exp  that  produce  them.  The  number  used  is  123456.654321. 


Table  4- 

-6:  Rounding  and  Truncation  of  123456.654321 

Value 

Int-exp 

Effect 

Returned 

-5 

Rounded  to  100,000s  and  truncated 

1 

-4 

Rounded  to  10,000s  and  truncated 

12 

-3 

Rounded  to  1000s  and  truncated 

123 

-2 

Rounded  to  100s  and  truncated 

1235 
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Table  4-6  (Cent.):  Rounding  and  Truncation  of  123456.654321 


Int-exp 

Effect 

Value 

Returned 

-1 

Rounded  to  10s  and  truncated 

12346 

0 

Rounded  to  units  and  truncated 

123457 

1 

Rounded  to  tenths  and  truncated 

123456.7 

2 

Rounded  to  hundredths  and  truncated 

123456.65 

3 

Rounded  to  thousandths  and  truncated 

123456.654 

4 

Rounded  to  ten-thousandths  and  truncated 

123456.6543 

5 

Rounded  to  hundred-thousandths  and  truncated 

123456.65432 

9,995 

Truncated  to  100,000s 

1 

9,996 

Truncated  to  10,000s 

12 

9,997 

Truncated  to  1000s 

123 

9,998 

Truncated  to  100s 

1234 

9,999 

Truncated  to  10s 

12345 

10,000 

Truncated  to  units 

123456 

10,001 

Truncated  to  tenths 

12345.6 

10,002 

Truncated  to  hundredths 

123456.65 

10,003 

Truncated  to  thousandths 

123456.654 

10,004 

Truncated  to  ten- thousandths 

123456.6543 

10,005 

Truncated  to  hundred- thousandths 

123456.65432 

Example 

10  DECLARE  STRING  str.exp,  str.var 
8tr_exp  *  ”9999.9999" 

Btr.var  *  PLACE$(8tr_exp,3) 
PRINT  8tr_var 

Output 

10000 
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POS 

The  POS  function  searches  for  a  substring  within  a  string  and  returns  the 
substring's  starting  character  position. 


Format 

int-var  =  P0S(str-exp1,  str-exp2,  int-exp) 


Syntax  Rules 

1.  Str^expl  specifies  the  main  string. 

2.  Str-exp2  specifies  the  substring. 

3.  Int-exp  specifies  the  character  position  in  the  main  string  at  which 
BASIC-PLUS-2  starts  the  search. 


Remarks 


1.  The  POS  function  searches  str-expl,  the  main  string,  for  the  first 
occurrence  of  str-exp2,  the  substring,  and  returns  the  position  of  the 
substring's  first  character. 

2.  The  position  returned  by  the  INSTR  function  is  the  number  of  charac¬ 
ters  from  the  beginning  of  the  string  regardless  of  the  value  specified 
in  int-exp, 

3.  If  int-exp  is  greater  than  the  length  of  the  main  string,  POS  returns  a 
value  of  zero. 

4.  POS  always  returns  the  character  position  in  the  main  string  at  which 
BASIC-PLUS-2  finds  the  substring,  with  the  following  exceptions: 

•  If  only  the  substring  is  null,  and  if  int-exp  is  less  than  or  equal  to 
zero,  POS  returns  a  value  of  1. 

•  If  only  the  substring  is  null,  and  if  int-exp  is  equal  to  or  greater 
than  1  and  less  than  or  equal  to  the  length  of  the  main  string, 
POS  returns  the  value  of  int-exp. 
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•  If  only  the  substring  is  null  and  if  int-exp  is  greater  than  the  length 
of  the  main  string,  POS  returns  the  main  string's  length  plus  1. 

•  If  only  the  main  string  is  null,  POS  returns  a  value  of  zero. 

•  If  both  the  main  string  and  the  substring  are  null,  POS  returns  1. 

5.  If  BASIC-PLUS-2  cannot  find  the  substring,  POS  returns  a  value  of 
zero. 

6.  If  int-exp  is  less  than  1,  BASIC-PLUS-2  assumes  a  starting  position  of 

1. 

7.  If  you  know  that  the  substring  is  not  near  the  beginning  of  the  string, 
specifying  a  starting  position  greater  than  1  speeds  program  execution 
by  reducing  the  number  of  characters  BASIC-PLUS-2  must  search. 

8.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 


Example 


400  DECLARE  STRING  main.str.  A 
sub.str 


DECLARE  INTEGER  first.char 
main_8tr  «  "ABCDEFG" 
sub.str  *  "DEFG" 

lirst.char  =  POSCmaln.str,  sub.str,  1) 
PRINT  first.char 


Output 


4 
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The  PRINT  statement  transfers  program  data  to  a  terminal  or  a  terminal- 
format  file. 

Format 

PRINT  [  #chnl-exp,  ]  [  output-list  ] 

output-list:  [exp] [ \  [  \  exp]  .. .  ' 


Syntax  Rules 


1.  ChnUexp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  ( # ).  If  you  do  not  specify  a  channel,  BASIC-PLUS-2  prints  to  the 
controlling  terminal. 

2.  Output4ist  specifies  the  expressions  to  be  printed  and  the  print  format 
to  be  used. 

3.  Exp  can  be  any  valid  expression. 

4.  A  separator  character  (comma  or  semicolon)  must  separate  each  exp. 
Separator  characters  control  the  print  format  as  follows: 

•  A  comma  ( , )  causes  BASIC-PLUS-2  to  skip  to  the  next  print  zone 
before  printing  the  expression. 

•  A  semicolon  (;)  causes  BASIC-PLUS-2  to  print  the  expression 
immediately  after  the  previous  expression. 


4-232  Statements  and  Functions 


PRINT 


Remarks 


1.  A  terminal  or  terminal-format  file  must  be  open  on  the  specified 
channel.  Your  current  terminal  is  always  open  on  channel  #0. 

2.  A  PRINT  line  has  an  integral  number  of  print  zones.  Note,  however, 
that  the  number  of  print  zones  in  a  line  differs  from  terminal  to 
terminal. 

3.  The  PRINT  statement  prints  string  constants  and  variables  exactly  as 
they  appear,  with  no  leading  or  trailing  spaces. 

4.  BASIC-PLUS-2  prints  quoted  string  literals  exactly  as  they  appear. 
Therefore,  you  can  print  quotation  marks,  commas,  and  other  charac¬ 
ters  by  enclosing  them  in  quotation  marks. 

5.  A  PRINT  statement  with  no  output-list  prints  a  blank  line. 

6.  An  expression  in  the  output-list  can  be  followed  by  more  than  one 
separator  character.  That  is,  you  can  omit  an  expression  and  specify 
where  the  next  expression  is  to  be  printed  by  the  use  of  multiple 
separator  characters.  For  example: 

200  PRINT  "Name" , , "Address  and  " ; "City" 

Output 

Name  Address  and  City 

In  this  example,  the  double  commas  after  "Name'"  cause 
BASIC-PLUS-2  to  skip  two  print  zones  before  printing  "Address 
and."  The  semicolon  causes  the  next  expression,  "City,"  to  be  printed 
immediately  after  the  preceding  expression.  Multiple  semicolons  have 
the  same  effect  as  a  single  semicolon. 

7.  When  printing  numeric  fields,  BASIC-PLUS-2  precedes  each  number 
with  a  space  or  minus  sign  ( - )  and  follows  it  with  a  space. 

8.  BASIC-PLUS-2  does  not  print  trailing  zeros  to  the  right  of  the  decimal 
point.  If  all  digits  to  the  right  of  the  decimal  point  are  zeros, 
BASIC-PLUS-2  omits  the  decimal  point  as  well. 

9.  For  REAL  numbers  (SINGLE  and  DOUBLE),  BASIC-PLUS-2  does  not 
print  more  than  six  digits  in  explicit  notation.  If  a  number  requires 
more  than  six  digits,  BASIC-PLUS-2  uses  E-format  and  precedes 
positive  exponents  with  a  plus  sign  (  +  ).  BASIC-PLUS-2  rounds  a 
floating-point  number  with  a  magnitude  between  0.1  and  1.0  to 

6  digits.  For  magnitudes  smaller  than  1,  BASIC-PLUS-2  prints  a 
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maximum  of  5  leading  zeros  and  6  digits  in  explicit  point  unsealed 

notation. 

10.  The  PRINT  statement  can  print  a  maximum  of: 

•  Three  digits  of  precision  for  BYTE  integers 

•  Five  digits  of  precision  for  WORD  integers 

•  Six  digits  of  precision  for  SINGLE  floating-point  numbers 

•  Ten  digits  of  precision  for  LONG  integers 

•  Sixteen  digits  of  precision  for  DOUBLE  floating-point  numbers 

•  The  string  length  for  STRING  values 

11.  If  there  is  a  comma  or  semicolon  following  the  last  item  in  ouiipuiAisi, 

BASIC-PLUS-2  does  the  following: 

•  When  printing  to  a  terminal,  BASIC-PLUS-2  does  not  generate  a 
line  terminator  after  printing  the  last  item.  The  next  item  printed 
with  a  PRINT  statement  is  printed  at  the  position  specified  by 
the  separator  character  following  the  last  item  in  the  first  PRINT 
statement. 

•  When  printing  to  a  terminal-format  file,  BASIC-PLUS-2  does  not 
write  out  the  record  until  a  PRINT  statement  without  trailing 
punctuation  executes. 

•  If  a  comma  is  positioned  after  the  last  print  zone,  the  output  is 
displayed  on  the  next  line. 

12.  If  no  punctuation  follows  the  last  item  in  the  output-list, 

BASIC-PLUS-2  does  the  following: 

•  When  printing  to  a  terminal,  BASIC-PLUS-2  generates  a  line 
terminator  after  printing  the  last  item. 

•  When  printing  to  a  terminal-format  file,  BASIC-PLUS-2  writes  out 
the  record  after  printing  the  last  item. 

13.  If  a  string  field  does  not  fit  on  the  current  line, 

BASIC-PLUS-2  does  the  following: 

•  When  printing  string  elements  to  a  terminal,  BASIC-PLUS-2  prints 
as  much  as  will  fit  on  the  current  line  and  prints  the  remainder  on 
the  next  line. 

•  When  printing  string  elements  to  a  terminal-format  file, 
BASIC-PLUS-2  prints  the  entire  element  on  the  next  line. 
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14.  If  a  numeric  field  is  the  first  field  in  a  line,  and  the  numeric  field  spans 
more  than  one  line,  BASIC-PLUS-2  prints  part  of  the  number  on  one 
line  and  the  remainder  on  the  next;  otherwise,  numeric  fields  are 
never  split  across  lines.  If  the  entire  field  cannot  be  printed  at  the  end 
of  one  line,  the  number  is  printed  on  the  next  line. 

15.  When  a  number's  trailing  space  does  not  fit  in  the  last  print  zone,  the 
number  is  printed  without  the  trailing  space. 


10  PRINT  "name  "age",  "height  ";  "weight" 

Output 

name  age  height  weight 
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PRINT  USING 

The  PRINT  USING  statement  generates  output  formatted  according  to  a 
format  string  (either  numeric  or  string)  to  a  terminal  or  a  terminal-format 
file. 


Format 

PRINT  [#chnl-exp][iSm  str-exp  | ;  |  output-list 
output-list:  [exp][{  [  ]  exp]  .. .  [ ;  1 


Syntax  Rules 


1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  ( # ).  If  you  do  not  specify  a  channel,  BASIC-PLUS-2  prints  to  the 
controlling  terminal. 

2.  Str-exp  is  the  format  string.  It  must  contain  at  least  one  valid  format 
field  and  must  be  followed  by  a  separator  (comma  or  semicolon)  and 
at  least  one  expression. 

3.  Output-list  specifies  the  expressions  to  be  printed. 

•  Exp  can  be  any  valid  expression  except  a  FORMATS  function. 

•  A  comma  or  semicolon  must  separate  each  expression. 

•  A  comma  or  semicolon  is  optional  after  the  last  expression  in  the 
list. 
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1.  The  PRINT  USING  statement  can  print  a  maximum  of: 

•  Three  digits  of  precision  for  BYTE  integers 

•  Five  digits  of  precision  for  WORD  integers 

•  Six  digits  of  precision  for  SINGLE  floating-point  numbers 

•  Ten  digits  of  precision  for  LONG  integers 

•  Sixteen  digits  of  precision  for  DOUBLE  floating-point  numbers 

•  The  string  length  for  STRING  values 

2.  A  terminal  or  terminal-format  file  must  be  open  on  the  specified 
channel  or  BASIC-PLUS-2  signals  an  error. 

3.  The  separator  characters  (comma  or  semicolon)  in  the  PRINT  USING 
statement  do  not  control  the  print  format.  The  print  format  is  con¬ 
trolled  by  the  format  string.  Therefore,  it  does  not  matter  whether  you 
use  a  comma  or  semicolon. 

4.  Formatting  Numeric  Output 

•  The  number  sign  ( # )  reserves  space  for  one  sign  or  digit. 

•  The  comma  ( , )  causes  BASIC-PLUS-2  to  insert  commas  before 
every  third  significant  digit  to  the  left  of  the  decimal  point.  In  the 
format  field,  the  comma  must  be  to  the  left  of  the  decimal  point 
and  to  the  right  of  the  rightmost  dollar  sign,  asterisk,  or  number 
sign.  A  comma  reserves  space  for  a  comma  or  digit. 

•  The  period  ( . )  inserts  a  decimal  point.  The  number  of  reserved 
places  on  either  side  of  the  period  determines  where  the  decimal 
point  appears  in  the  output. 

•  The  hyphen  (-)  reserves  space  for  a  sign  and  specifies  trailing 
minus  sign  format.  If  present,  it  must  be  the  last  character  in  the 
format  field.  It  causes  BASIC-PLUS-2  to  print  negative  numbers 
with  a  minus  sign  after  the  last  digit,  and  positive  numbers  with  a 
trailing  space.  The  hyphen  (-)  can  be  used  as  part  of  a  dollar  sign 
( $$ )  format  field. 

•  The  letters  CD  (Credit/Debit)  enclosed  in  angle  brackets 

(  <CD>  )  print  CR  (Credit  Record)  after  negative  numbers, 
or  zero  and  DR  (Debit  Record)  after  positive  numbers.  If 
present,  they  must  be  the  last  characters  in  the  format  field. 

The  Credit/Debit  format  can  be  used  as  part  of  a  dollar  sign  ($$) 
format  field. 
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12.  If  a  number  does  not  fit  in  the  specified  format  field,  BASIC-PLUS-2 

prints  a  percent  sign  warning  symbol  (%),  followed  by  the  number  in 

PRINT  format. 

13.  Formatting  String  Output 

•  Format  string  characters  control  string  output  and  can  be  entered 
only  as  uppercase  characters.  All  format  characters  except  the 
backslash  and  exclamation  point  must  start  with  a  single  quotation 
mark  (').  A  single  quote  by  itself  reserves  one  character  position. 
A  single  quote  followed  by  any  format  characters  marks  the 
beginning  of  a  character  format  field  and  reserves  one  character 
position. 

•  L  reserves  one  character  position.  The  number  of  Ls  plus  the 
leading  single  quote  determines  the  field's  size.  BASIC-PLUS-2 
left-justifies  the  print  expression  and  pads  with  spaces  if  the  print 
expression  is  less  than  or  equal  to  the  field's  width.  If  the  print 
expression  is  larger  than  the  field,  BASIC-PLUS-2  left-justifies  the 
expression  and  truncates  its  right  side  to  fit  the  field. 

•  R  reserves  one  character  position.  The  number  of  Rs  plus  the 
leading  single  quote  determines  the  field's  size.  BASIC-PLUS-2 
right-justifies  the  print  expression  and  pads  with  spaces  if  the  print 
expression  is  less  than  or  equal  to  the  field's  width.  If  the  print 
expression  is  larger  than  the  field,  BASIC-PLUS-2  truncates  the 
right  side  to  fit  the  field. 

•  C  reserves  one  character  position.  The  number  of  Cs  plus  the 
leading  single  quote  determines  the  field's  size.  If  the  string 
does  not  fit  in  the  field,  BASIC-PLUS-2  truncates  its  right  side; 
otherwise,  BASIC-PLUS-2  centers  the  print  expression  in  this 
field.  If  the  string  cannot  be  centered  exactly,  it  is  offset  one 
character  to  the  left. 

•  E  reserves  one  character  position.  The  number  of  Es  plus  the 
leading  single  quote  determines  the  field's  size.  BASIC-PLUS-2 
left-justifies  the  print  expression  if  it  is  less  than  or  equal  to  the 
field's  width  and  pads  with  spaces;  otherwise,  BASIC-PLUS-2 
expands  the  field  to  hold  the  entire  print  expression. 

•  Two  backslashes  (\  \)  when  separated  by  n  spaces  reserve  n+2 
character  positions.  PRINT  USING  left-justifies  the  string  in  this 
field.  BASIC-PLUS-2  does  not  allow  a  leading  quotation  mark 
with  this  format. 

•  An  exclamation  point  (!)  creates  a  1 -character  field.  The  exclama¬ 
tion  point  both  starts  and  ends  the  field.  BASIC-PLUS-2  does  not 
allow  a  leading  quotation  mark  with  this  format. 
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14.  BASIC-PLUS-2  interprets  any  other  characters  in  the  format  string  as 
string  literals  and  prints  them  exactly  as  they  appear. 

15.  If  a  comma  or  semicolon  follows  the  last  item,  output-list,  the  follow¬ 
ing  occurs: 

•  When  printing  to  a  terminal,  BASIC-PLUS-2  does  not  generate  a 
line  terminator  after  printing  the  last  item.  The  next  item  printed 
with  a  PRINT  statement  is  printed  at  the  position  specified  by 
the  separator  character  following  the  last  item  in  the  first  PRINT 
statement. 

•  When  printing  to  a  terminal-format  file,  BASIC-PLUS-2  does  not 
write  out  the  record  until  a  PRINT  statement  without  trailing 
punctuation  executes. 

16.  If  no  punctuation  follows  the  last  item  in  output-list,  the  following 
occurs: 

•  When  printing  to  a  terminal,  BASIC-PLUS-2  generates  a  line 
terminator  after  printing  the  last  item. 

•  When  printing  to  a  terminal-format  file,  BASIC-PLUS-2  writes  out 
the  record  after  printing  the  last  item. 


Examples 


Example  1 

200  PRINT  USING  -12. 345 

PRINT  USING  ■’«*.»«#",  12. 346 

Output  1 

-12.345 

12.346 

Example  2 

30  INPUT  "Your  Name" ;  Winner* 

Jackpot  >  10000.0 

PRINT  USING  "CONGRATULATIONS.  'EEEEEEEEE,  YOU  WON  |$«»«»«.««" .  Wlnnerl.  Jackpot 
END 

Output  2 

Your  Name?  Hortenee  Corabelle 

CONGRATULATIONS.  Hortenee  Corabelle.  YOU  WON  $10000.00 
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The  PROGRAM  statement  allows  you  to  identify  a  main  program  with  a 
name  other  than  the  file  name. 


Format 

PROGRAM  prog-name 

Syntax  Rules 

Prog-name  specifies  the  module  name  of  the  compiled  source  and  cannot 
be  the  same  as  any  SUB  or  FUNCTION  name. 

Remarks 


1.  The  PROGRAM  statement  must  be  the  first  statement  in  a  main 
program  and  can  be  preceded  only  by  comment  fields  and  lexical 
directives. 

2.  If  you  examine  the  program  using  the  BASIC-PLUS-2  Debugger,  the 
program  name  you  specify  will  be  the  module  name  used. 

3.  The  PROGRAM  statement  is  optional;  BASIC-PLUS-2  allows  you 
to  specify  an  END  PROGRAM  statement  and  an  EXIT  PROGRAM 
statement  without  a  matching  PROGRAM  statement. 


Example 


20  PROGRAM  flrat.teat 

END  PROGRAM 
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The  PUT  statement  transfers  data  from  the  record  buffer  to  a  file.  PUT 
statements  are  valid  on  RMS  sequential,  relative,  indexed,  and  block  I/O 
files.  You  cannot  use  PUT  statements  on  terminal-format  files,  virtual 
array  files,  or  files  opened  with  the  ORGANIZATION  UNDEFINED 
clause. 


Format 

PUT  i^chnl-exp  [ ,  RECORD  num-exp  [ ,  COUNT  int-exp  ] ] 


Syntax  Rules 


1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 

2.  The  RECORD  clause  allows  you  to  randomly  write  records  to  a  rela¬ 
tive  or  sequential  fixed  file  by  specifying  the  record  number. 

Num-exp  must  be  between  1  and  the  maximum  record  number  al¬ 
lowed  for  the  file.  BASIC-PLUS-2  does  not  allow  you  to  use  the 
RECORD  clause  on  sequential  variable,  sequential  stream,  or  indexed 
files. 

3.  Int-exp  in  the  COUNT  clause  specifies  the  record's  size.  If  there  is 
no  COUNT  clause,  the  record's  size  is  that  defined  by  the  MAP  or 
RECORDSIZE  clause  in  the  OPEN  statement.  The  RECORDSIZE 
clause  overrides  the  MAP  clause. 

•  If  you  write  a  record  to  a  file  with  variable-length  records,  int-exp 
must  be  an  integer  from  zero  through  the  maximum  record  size 
specified  in  the  OPEN  statement. 

•  If  int-exp  equals  zero,  the  entire  record  is  written  to  the  file. 

•  If  you  write  a  record  to  a  file  with  fixed-length  records,  the 
COUNT  clause  serves  no  purpose.  If  used,  int-exp  must  equal  the 
record  size  specified  in  the  OPEN  statement. 
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Remarks 


1.  For  sequential  access,  the  file  associated  with  chnl-exp  must  be  open 
with  ACCESS  WRITE,  MODIFY,  SCRATCH,  or  APPEND. 

2.  For  random  access,  the  relative  or  sequential  fixed  file  associated  with 
chnl-exp  must  be  open  with  ACCESS  WRITE  or  MODIFY. 

3.  To  add  records  to  an  existing  sequential  file,  open  it  with  ACCESS 
APPEND.  If  you  are  not  at  the  end  of  the  file  when  attempting  a 
PUT  to  a  sequential  file,  BASIC -PLUS-2  signals  "Not  at  end  of  file" 
(ERR=149). 

4.  After  a  PUT  statement  executes,  there  is  no  current  record  pointer. 

The  next  record  pointer  is  set  as  follows: 

•  For  sequential  files,  variable  and  stream  PUT  operations  set  the 
next  record  pointer  to  the  end  of  the  file. 

•  For  relative  and  sequentially  fixed  files,  a  sequential  PUT  operation 
sets  the  next  record  pointer  to  the  next  record  plus  1. 

•  For  relative  and  sequential  fixed  files,  a  random  PUT  operation 
leaves  the  next  record  pointer  unchanged. 

•  For  indexed  files,  a  PUT  operation  leaves  the  next  record  pointer 
unchanged. 

5.  When  you  specify  a  RECORD  clause,  BASIC -PLUS-2  evaluates  num- 
exp  and  uses  this  value  as  the  relative  record  number  of  the  target 
cell. 

•  If  the  target  cell  is  empty  or  occupied  by  a  deleted  record, 
BASIC-PLUS-2  places  the  record  in  that  cell. 

•  If  there  is  a  record  in  the  target  cell  and  the  file  has  not  been 
opened  as  a  VIRTUAL  file,  the  PUT  statement  fails,  and 
BASIC-PLUS-2  signals  the  error  "Record  already  exists" 
(ERR=153). 

6.  A  PUT  statement  with  no  RECORD  clause  writes  records  to  the  file  as 
follows: 

•  For  sequential  variable  and  stream  files,  a  PUT  operation  adds  a 
record  at  the  end  of  the  file. 

•  For  relative  and  sequential  fixed  files,  a  PUT  operation  places  the 
record  in  the  empty  cell  pointed  to  by  the  next  record  pointer.  If 
the  file  is  empty,  the  first  PUT  operation  places  a  record  in  cell 
number  1,  the  second  in  cell  number  2,  and  so  on. 
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•  For  indexed  files,  RMS  stores  records  in  order  of  ascending  pri¬ 
mary  key  value  and  updates  all  indexes  so  that  they  point  to  the 
record. 

7.  When  you  open  a  file  as  ORGANIZATION  VIRTUAL,  the  file  you 
open  is  a  sequential  fixed  file  with  a  record  size  that  is  a  multiple 
of  512  bytes.  You  can  then  access  the  file  with  the  FIND,  GET, 

PUT,  or  UPDATE  statements  or  through  one  or  more  virtual  arrays. 
BASIC-PLUS-2  allows  you  to  overwrite  existing  records  in  a  file  not 
containing  virtual  arrays  and  opened  as  ORGANIZATION  VIRTUAL 
by  using  the  PUT  statement  with  a  RECORD  clause.  All  other  organi¬ 
zations  require  the  UPDATE  statement  to  change  an  existing  record.  It 
is  recommended  that  you  also  use  the  UPDATE  statement  to  change 
existing  records  in  VIRTUAL  files  that  do  not  contain  virtual  arrays. 

8.  If  an  existing  record  in  an  indexed  file  has  a  record  with  the  same  key 
value  as  the  one  you  want  to  put  in  the  file,  BASIC-PLUS-2  signals 
the  error  "Duplicate  key  detected"  (ERR=134)  if  you  did  not  specify 
DUPLICATES  for  the  key  in  the  OPEN  statement.  If  you  specified 
DUPLICATES,  RMS  stores  the  duplicate  records  in  a  first-in/first-out 
sequence. 

9.  The  number  specified  in  the  COUNT  clause  determines  how  many 
bytes  are  transferred  from  the  buffer  to  a  file: 

•  If  you  have  not  completely  filled  the  record  buffer  before  executing 
a  PUT  statement,  BASIC-PLUS-2  pads  the  record  with  nulls  to 
equal  the  specified  value. 

•  If  the  specified  COUNT  value  is  less  than  the  buffer  size,  the 
record  is  truncated  to  equal  the  specified  value. 

•  The  number  in  the  COUNT  clause  must  not  exceed  the  size 
specified  in  the  MAP  or  RECORDSIZE  clause  in  the  OPEN 
statement  or  BASIC-PLUS-2  signals  "Size  of  record  invalid" 
(ERR=156). 

•  For  files  with  fixed-length  records,  the  number  in  the  COUNT 
clause  must  match  the  record  size. 

10.  Although  block  I/O  files  are  implemented  through  RMS- 11  on  RSX 
systems  when  you  write  a  record  to  a  block  I/O  file,  RMS- 11  does 
not  perform  the  same  error  checking  as  with  relative  files.  A  PUT 
will  write  a  record  to  a  disk  block  specified  in  the  RECORD  clause, 
regardless  of  whether  the  block  already  contains  a  record.  See  the 
BASIC~PLUS‘2  User's  Guide  for  more  information  on  RMS-11  block 
I/O  files. 
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11.  See  the  BASIC-PLUS-2  User's  Guide  for  more  information  on  RSTS/E 
native  mode  files. 


Examples 


Example  1 

10  I Sequential ,  Relative,  Indexed,  and  Virtual  Files 
PUT  #3,  COUNT  66X 

Example  2 

10  ! Relative  and  Virtual  Files  Only 

PUT  #6,  RECORD  133,  COUNT  16% 
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QUO$ 

The  QUO$  function  returns  a  numeric  string  that  is  the  quotient  of  two 
numeric  strings.  The  precision  of  the  returned  numeric  string  depends  on 
the  value  of  an  integer  argument. 


Format 

str-var  =  Q\}0$(str-exp1,  str-exp2,  int-exp) 


Syntax  Rules 


1.  Str-expl  and  str-exp2  specify  the  numeric  strings  you  want  to  divide. 
A  numeric  string  can  have  ASCII  digits,  an  optional  minus  sign  (-), 
and  an  optional  decimal  point  ( . ) 

2.  Int-exp  specifies  the  numeric  precision  of  str-exp.  Table  4-6  shows 
examples  of  rounding  and  truncation  and  the  values  of  int-exp  that 
produce  them. 


Remarks 


1.  If  str-exp  consists  of  more  than  60  characters,  BASIC-PLUS-2  signals 
the  error  "Illegal  number"  (ERR=52). 

2.  Str-exp  is  rounded  or  truncated,  or  both,  according  to  the  value  of 
int-exp. 

3.  If  int-exp  is  between  —60  and  60,  rounding  and  truncation  occur  as 
follows: 

•  For  positive  integer  expressions,  rounding  occurs  to  the  right  of 
the  decimal  place.  For  example,  if  int-exp  is  1,  rounding  occurs 
one  digit  to  the  right  of  the  decimal  place  (the  number  is  rounded 
to  the  nearest  tenth).  If  int-exp  is  2,  rounding  occurs  two  digits 
to  the  right  of  the  decimal  place  (the  number  is  rounded  to  the 
nearest  hundredth),  and  so  on. 

•  If  int-exp  is  zero,  BASIC-PLUS-2  rounds  to  the  nearest  unit. 
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•  For  negative  integer  expressions,  rounding  occurs  to  the  left  of  the 
decimal  point.  If  int-exp  is  -1,  for  example,  BASlC-PLUS-2  moves 
the  decimal  point  one  place  to  the  left,  then  rounds  to  units.  If 
int-exp  is  -2,  rounding  occurs  two  places  to  the  left  of  the  decimal 
point;  BASlC-PLUS-2  moves  the  decimal  point  two  places  to  the 
left,  then  rounds  to  tens. 

4.  If  int-exp  is  between  9940  and  10,060,  truncation  occurs  as  follows: 

•  If  int-exp  is  10000,  BASIC-PLUS-2  truncates  the  number  at  the 
decimal  point. 

•  If  int-exp  is  greater  than  10,000  (10,000  plus  n)  BASIC-PLUS-2 
truncates  the  numeric  string  n  places  to  the  right  of  the  decimal 
point.  For  example,  if  int-exp  is  10,001  (10,000  plus  1), 
BASIC-PLUS-2  truncates  the  number  starting  one  place  to  the 
right  of  the  decimal  point.  If  int-exp  is  10,002  (10,000  plus  2), 
BASIC-PLUS-2  truncates  the  number  starting  two  places  to  the 
right  of  the  decimal  point,  and  so  on. 

•  If  int-exp  is  less  than  10,000  (10,000  minus  n),  BASIC-PLUS-2 
truncates  the  numeric  string  n  places  to  the  left  of  the  decimal 
point.  For  example,  if  int-exp  is  9999  (10,000  minus  1), 
BASIC-PLUS-2  truncates  the  number  starting  one  place  to  the  left 
of  the  decimal  point.  If  9998  (10,000  minus  2),  BASIC-PLUS-2 
truncates  starting  two  places  to  the  left  of  the  decimal  point,  and 
so  on. 

5.  If  int-exp  is  not  between  -60  and  60  or  9940  and  10,060, 

BASIC -PLUS-2  returns  a  value  of  zero. 

6.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 


Example 


100  DECLARE  STRING  num.strl,  k 
nuin.8tr2 ,  k 
quotient 

num.strl  *  "468996.43” 

num_8tr2  =  "123222.444" 

quotient  *  QUOKnum.etrl ,  num_8tr2,  2) 

PRINT  quotient 

Output 

3.72 
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RAD$ 


The  RAD$  function  converts  a  specified  integer  in  Radix-50  format  to  a 
3-character  string. 


Format 

str-var  =  RMi$(int-var} 

Syntax  Rules 

None. 

Remarks 


1.  The  RAD$  function  converts  int-var  to  a  3-character  string  in  Radix-50 
format  and  stores  it  in  str-var.  Radix-50  format  allows  you  to  store 
three  characters  of  data  as  a  2-byte  integer. 

2.  If  you  specify  a  floating-point  variable  for  int-var,  BASIC-PLUS-2 
truncates  it  to  an  integer  of  the  default  size. 

3.  See  the  BASIC-PLUS-2  User's  Guide  for  information  on  the  Radix-50 
character  set  and  ASCII/Radix-50  equivalents. 


Example 


100  DECLARE  STRING  radix 
radix  *  RADI (1683) 
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RANDOMIZE 

The  RANDOMIZE  statement  gives  the  random  number  function  RND  a 
new  starting  value. 


Format 

r  RANDOMIZE  1 
I  RANDOM  J 


Syntax  Rules 

None. 


Remarks 


1.  Without  the  RANDOMIZE  statement,  successive  runs  of  the  same 
program  generate  the  same  random  number  sequence. 

2.  If  you  use  the  RANDOMIZE  statement  before  invoking  the  RND 
function,  the  starting  point  changes  for  each  run.  Therefore,  a  different 
random  number  sequence  appears  each  time. 


Example 


20  DECLARE  REAL  random.nuni 
RANDOMIZE 

FOR  I  «  1  TO  2 

random.num  *  RND 
PRINT  random_n\im 
NEXT  I 

Output 

.379784 

.311672 
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RCTRLC 


The  RCTRLC  function  disables  CTRL/C  trapping. 


Format 

=  RCTRLC 

Syntax  Rules 

None. 

Remarks 


1.  After  BASIC-PLUS-2  executes  the  RCTRLC  function,  a  CTRL/C  typed 
at  the  terminal  returns  you  to  DCL  command  level  or  to  the  BASIC 
environment. 

2.  RCTRLC  always  returns  a  value  of  zero. 


Example 

100  Y  »  RCTRLC 
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RCTRLO 

The  RCTRLO  function  cancels  the  effect  of  a  CTRL/O  typed  on  a  terminal 
opened  on  a  specified  channel. 

Format 

int-var  =  RCTRLO  (chnl-exp) 

Syntax  Rules 

Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number  associ¬ 
ated  with  an  open  terminal.  It  cannot  be  preceded  by  a  number 
sign  (#). 


Remarks 


1.  If  you  type  a  CTRL/O  to  cancel  terminal  output,  nothing  is  printed 
on  the  specified  terminal  until  your  program  executes  the  RCTRLO 
or  until  you  type  another  CTRL/O,  at  which  time  normal  terminal 
output  resumes. 

2.  The  RCTRLO  function  always  returns  a  value  of  zero. 

3.  RCTRLO  has  no  effect  if  the  specified  channel  is  open  to  a  device  that 
does  not  use  the  CTRL/O  convention. 
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Example 


10  PRINT  "A"  FOR  IX  «  IX  TO  lOX 
YX  •  RCTRLO (OX) 

PRINT  "Normal  output  is  resumsd" 

Output 

A 

A 

A 

A 
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The  READ  statement  assigns  values  from  a  DATA  statement  to  variables. 


Format 

READ  var,  . . . 

Syntax  Rules 

None. 

Remarks 


1.  If  your  program  has  a  READ  statement  without  DATA  statements, 
BASIC-PLUS-2  signals  a  compile-time  error. 

2.  When  BASIC-PLUS-2  initializes  a  program  unit,  it  forms  a  data 
sequence  of  all  values  in  all  DATA  statements.  An  internal  pointer 
points  to  the  first  value  in  the  sequence. 

3.  When  BASIC-PLUS-2  executes  a  READ  statement,  it  sequentially 
assigns  values  from  the  data  sequence  to  variables  in  the  READ 
statement  variable  list.  As  BASIC-PLUS-2  assigns  each  value,  it 
advances  the  internal  pointer  to  the  next  value. 

4.  BASIC-PLUS-2  signals  the  error  "Out  of  data"  (ERR=57)  if  there  are 
fewer  data  elements  than  READ  statements.  Extra  data  elements  are 
ignored. 

5.  The  data  type  of  the  value  must  agree  with  the  data  type  of  the 
variable  to  which  it  is  assigned  or  BASIC-PLUS-2  signals  "Data  format 
error"  (ERR=50). 

6.  If  you  read  a  string  variable  and  the  DATA  element  is  an  unquoted 
string,  BASIC-PLUS-2  ignores  leading  and  trailing  spaces.  If  the 
DATA  element  contains  any  commas,  they  must  be  inside  quotation 
marks. 
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7.  BASIC-PLUS-2  evaluates  subscript  expressions  in  the  variable  list 
after  it  assigns  a  value  to  the  preceding  variable,  and  before  it  assigns 
a  value  to  the  subscripted  variable.  For  instance,  in  the  following 
example,  BASIC-PLUS-2  assigns  the  value  of  10  to  variable  A,  then 
assigns  the  string  LESTER  to  array  element  A$(A). 

100  READ  A,  A$(10) 


900  DATA  10,  LESTER 

The  string,  LESTER,  will  be  assigned  to  A$(10). 


Example 


10  DECLARE  STRING  A.B.C 
READ  A.B.C 
DATA  "X".  "Y".  "Z" 
PRINT  A  B  ♦  C 

Output 

XYZ 
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REAL 


The  REAL  function  converts  a  numeric  expression  or  numeric  string  to  a 
specified  or  default  floating-point  data  type. 


Format 


real-var  =  KMfexp 


.SINGLE 
.  .DOUBLE  . 


I 


Syntax  Rules 

Exp  can  be  either  numeric  or  string.  If  a  string,  it  can  contain  the  ASCII 
digits  0  through  9,  uppercase  E,  a  plus  sign  (+),  a  minus  sign  (-),  and  a 
period  ( . ). 


Remarks 


1.  BASIC-PLUS-2  evaluates  exp,  then  converts  it  to  the  specified  REAL 
size.  If  you  do  not  specify  a  size,  BASIC-PLUS-2  uses  the  default 
REAL  size. 

2.  BASIC-PLUS-2  ignores  leading  and  trailing  spaces  and  tabs  if  exp  is  a 
string. 

3.  The  REAL  function  returns  a  value  of  zero  when  a  string  argument 
contains  only  spaces  and  tabs,  or  when  the  argument  is  null. 
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Example 


100  DECLARE  STRING  any.num 

INPUT  "Enter  a  number" ; any _num 
PRINT  REALCany.num.  DOUBLE) 

Output 

Enter  a  number?  123095959 
. 123096E+09 
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RECOUNT 

The  RECOUNT  function  returns  the  number  of  characters  transferred  by 
the  last  input  operation. 

Format 

//;f-rdr=:  RECOUNT 


Syntax  Rules 

None. 


Remarks 


1.  The  RECOUNT  value  is  reset  by  every  input  operation  on  any  chan¬ 
nel,  including  channel  #0. 

•  After  an  input  operation  from  your  terminal,  RECOUNT  con¬ 
tains  the  number  of  characters  (bytes)  transferred  (including  line 
terminators). 

•  After  accessing  a  file  record,  RECOUNT  contains  the  number  of 
characters  in  the  record. 

2.  Because  RECOUNT  is  reset  by  every  input  operation  on  any  channel, 
you  should  copy  the  RECOUNT  value  to  a  different  storage  location 
before  executing  another  input  operation. 

3.  If  an  error  occurs  during  an  input  operation,  the  value  of  RECOUNT 
is  undefined. 

4.  RECOUNT  is  unreliable  after  a  CTRL/C  interrupt  because  the 
CTRL/C  trap  may  have  occurred  before  BASIC-PLUS-2  set  the  value 
for  RECOUNT. 

5.  The  RECOUNT  function  returns  a  WORD  value. 
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Example 


200  DECLARE  INTEGER  character.count 

INPUT  "Enter  a  sequence  of  numeric  characters" ; character.count 
character.count  ■  RECOUNT 

PRINT  character.count; "characters  received  (Including  CR  and  LF)" 

Output 

Enter  a  sequence  of  numeric  characters?  12345678 
10  characters  received  (Including  CR  and  LF) 
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REM 


The  REM  statement  allows  you  to  document  your  program. 


Format 

REM  [comment] 


Syntax  Rules 


1.  REM  must  be  the  only  statement  on  the  line  or  the  last  statement  on  a 
multi-statement  line. 

2.  BASlC-PLUS-2  interprets  every  character  between  the  keyword  REM 
and  the  next  line  number  as  part  of  the  comment. 

3.  Because  the  REM  statement  is  not  executable,  you  can  place  it  any¬ 
where  in  a  program,  except  where  other  statements,  such  as  SUB  and 
END  SUB,  must  be  the  first  or  last  statement  in  a  program  unit. 


Remarks 


1.  When  the  REM  statement  is  the  first  statement  on  a  line-numbered 
line,  BASIC-PLUS-2  treats  any  reference  to  that  line  number  as  a 
reference  to  the  next  higher-numbered  executable  statement. 

2.  The  REM  statement  is  similar  to  the  comment  field  that  begins  with 
an  exclamation  point,  with  one  exception:  the  REM  statement  must  be 
the  last  statement  on  a  BASIC  line.  The  exclamation  point  comment 
field  can  be  ended  with  another  exclamation  point  or  a  line  terminator 
and  followed  by  a  BASIC-PLUS-2  statement.  See  Chapter  1  of  this 
manual  for  more  information  on  the  comment  field. 
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Example 


10  REM  This  is  a  multi -line  comment 
All  the  text  up  to  BASIC  line  20 
is  a  part  of  this  REM  statement. 
Any  BASIC  statements  on  line  10 
are  ignored. 

PRINT  "This  does  not  execute" . 

20  PRINT  "This  will  execute" 

Output 

This  will  execute 
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REMAP 

The  REMAP  statement  defines  or  redefines  the  position  in  the  storage  area 
of  variables  named  in  the  MAP  DYNAMIC  statement. 

Format 

REMAP  (map-dyn-namel  remap-item,  . . . 

map-dyn-name: 

f  map-name  1 

1  static-str-var  j 

num-var 

remap-item:  < 

num-array-name  ( [  int-exp,  . . .  ] } 
str-var  [ = int-exp  ] 

str-array-name  ( [  int-exp,  ...]}[= int-exp  ] 

► 

[  data-type  ]  FILL  [  ( int-exp)  ][= int-exp  ] 
r\lL%  [( int-exp }  ] 

.  FILLS  [  ( int-exp  }  ][=  int-exp  ] 

Syntax  Rules 


1.  Map-dyn-name  can  be  either  a  map  name  or  a  static  string  variable. 

•  Map-name  is  the  storage  area  named  in  a  MAP  statement. 

•  If  you  specify  a  map  name,  then  a  MAP  statement  with  the  same 
name  must  precede  both  the  MAP  DYNAMIC  statement  and  the 
REMAP  statement. 

•  When  you  specify  a  static  string  variable,  the  string  must  be 
declared  before  you  can  specify  a  MAP  DYNAMIC  statement  or  a 
REMAP  statement. 

•  If  you  specify  a  static-str-var,  the  following  restrictions  apply: 

—  Static-str-var  cannot  be  a  string  constant. 
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Static-str-var  cannot  be  the  same  as  any  previously  declared 
map-item  in  a  MAP  DYNAMIC  statement. 

—  Static-str-var  cannot  be  a  subscripted  variable. 

2.  Remap-item  names  a  variable,  array,  or  array  element  declared  in  a 
preceding  MAP  DYNAMIC  statement: 

•  Num-var  specifies  a  numeric  variable  or  array  element. 
Num-array-name  followed  by  a  set  of  empty  parentheses  specifies 
an  entire  numeric  array. 

•  Str-var  specifies  a  string  variable  or  array  element.  Str-array-name 
followed  by  a  set  of  empty  parentheses  specifies  an  entire  fixed- 
length  string  array.  You  can  specify  the  number  of  bytes  to  be 
reserved  for  string  variables  and  array  elements  with  the  =int-exp 
clause.  The  default  string  length  is  16. 

3.  Remap-item  can  also  be  a  FILL  item.  The  FILL,  FILL%,  and  FILLS 
keywords  let  you  reserve  parts  of  the  record  buffer.  Int-exp  specifies 
the  number  of  FILL  items  to  be  reserved.  The  =int-exp  clause  allows 
you  to  specify  the  number  of  bytes  to  be  reserved  for  string  FILL 
items.  Table  4-2  describes  FILL  item  format  and  storage  allocation. 

NOTE 

In  the  FILL  clause,  (int-exp)  represents  a  repeat  count,  not 
an  array  subscript.  FILL  («),  for  example,  represents  n 
elements,  not  h  +  1. 


4.  All  remap-items,  except  FILL  items,  must  have  been  named  in  a 
previous  MAP  DYNAMIC  statement,  or  BASIC-PLUS-2  signals  an 
error. 

5.  Data-type  can  be  any  BASIC-PLUS-2  data  type  keyword.  Data  type 
keywords  and  their  size,  range,  and  precision  are  listed  in  Table  1-2 
in  this  manual.  You  can  specify  a  data  type  only  for  FILL  items.  If 
you  do  not  specify  a  data  type,  FILL  items  take  the  current  default 
data  type  and  size. 

6.  Remap-items  must  be  separated  with  commas. 
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Remarks 


1.  The  REMAP  statement  does  not  affect  the  amount  of  storage  allocated 
to  the  map  area. 

2.  Each  time  a  REMAP  statement  executes,  BASIC-PLUS-2  sets  record 
pointers  to  the  named  map  area  for  the  specified  variables  from  left  to 
right. 

3.  The  REMAP  statement  must  be  preceded  by  a  MAP  DYNAMIC 
statement  or  BASIC-PLUS-2  signals  the  error  "No  such  MAP  area 

<name>  The  MAP  statement  or  static  string  variable  creates  a 
named  area  of  static  storage,  the  MAP  DYNAMIC  statement  specifies 
the  variables  whose  positions  can  change  at  run  time,  and  the  REMAP 
statement  specifies  the  new  positions  for  the  variables  names  in  the 
MAP  DYNAMIC  statement. 

4.  Before  you  can  specify  a  map  name  in  a  REMAP  statement,  there 
must  be  a  MAP  statement  in  the  program  unit  with  the  same  map 
name;  otherwise,  BASIC-PLUS-2  signals  the  error  "  <Name>  is  not 
a  DYNAMIC  MAP  variable  of  MAP  <name>  ."  Similarly,  before  you 
can  specify  a  static  string  variable  in  a  REMAP  statement,  the  string 
variable  must  be  declared  or  BASIC-PLUS-2  signals  the  same  error 
message. 

5.  If  a  static  string  variable  is  the  same  as  a  map  name,  BASIC-PLUS-2 
overrides  the  static  string  name  and  uses  the  map  name. 

6.  Until  the  REMAP  statement  executes,  all  variables  named  in  the  MAP 
DYNAMIC  statement  point  to  the  first  byte  of  the  MAP  area  and  all 
string  variables  have  a  length  of  zero.  When  the  REMAP  statement 
executes,  BASIC-PLUS-2  sets  the  internal  pointers  as  specified  in  the 
REMAP  statement.  For  example: 

100  MAP  (DUMMY)  STRING  map.bulfer  *  60 

MAP  DYNAMIC  (DUMMY)  LONG  A,  STRING  B.  SINGLE  C(7) 

REMAP  (DUMMY)  B*14.  A,  C() 

The  REMAP  statement  sets  a  pointer  to  byte  1  of  DUMMY  for  string 
variable  B,  a  pointer  to  byte  15  for  LONG  variable  A,  and  pointers  to 
bytes  19,  23,  27,  31,  35,  39,  43,  and  47  for  the  elements  in  SINGLE 
array  C. 
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7.  You  can  use  the  REMAP  statement  to  redefine  the  pointer  for  an  array 
element  or  variable  more  than  once  in  a  single  REMAP  statement.  For 
example: 

100  MAP  (DUMMY)  STRING  FILL  -  48 

MAP  DYNAMIC  (DUMMY)  LONG  A,  B(10) 

REMAP  (DUMMY)  B(),  B(0) 

This  REMAP  statement  sets  a  pointer  to  byte  1  in  DUMMY  for  array 
B.  Because  array  B  uses  a  total  of  44  bytes,  the  pointer  for  the  first 
element  of  array  B,  B(0)  points  to  byte  45.  References  to  array  element 
B(0)  will  be  to  bytes  45  through  48.  Pointers  for  array  elements  1 
through  10  are  set  to  bytes  5,  9,  13,  17,  and  so  forth. 

8.  Because  the  REMAP  statement  is  local  to  a  program  module,  it  affects 
pointers  only  in  the  program  module  in  which  it  executes. 


Examples 


Example  1 

20  DECLARE  LONG  CONSTANT  emp_f ixed_inlo  =4+9+2 
MAP  (employ)  LONG  badge.  ^ 

STRING  social.sec.num  =9,  A 

BYTE  name.length .  A 

address.length.  A 

FILL  (60) 

MAP  DYNAMIC  (employ)  STRING  emp.name,  A 

emp_ address 


WHILE  ly. 

GET  «1 

REMAP  (employ)  STRING  FILL  =  emp.f ixed.inf o.  A 

emp.name  =  name.length .  A 

emp.address  *  address.length 

PRINT  emp.name 
PRINT  emp.address 
PRINT 

NEXT 

END 
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Example  2 

000  SOB  deblock  (STRING  input.rec,  STRING  ItemO) 
MAP  DYNAMIC  (input.rec)  STRING  A(3) 

REMAP  (Input.rec)  b 
A(l)  -  6.  A 
A(3)  -  3,  A 
A(3)  -  4 
FOR  I  «  1  TO  3 
item(I)  •  A(I) 

NEXT  I 
END  SUB 
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RESET 


The  RESET  statement  is  a  synonym  for  the  RESTORE  statement.  See  the 
RESTORE  statement  for  more  information. 


Format 

RESET  [  #chnl-exp  [,  KEY  #int-exp  ]  ] 
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RESTORE 


The  RESTORE  statement  resets  the  DATA  pointer  to  the  beginning  of  the 
DATA  sequence,  or  sets  the  record  pointer  to  the  first  record  in  a  file. 


Format 

RESTORE  [  #chnl-exp  [,  KEY  #int-exp  ]  ] 


Syntax  Rules 

1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 

2.  Int-exp  must  be  an  integer  from  zero  through  the  number  of  keys  in 
the  file  minus  1.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 


Remarks 


1.  If  you  do  not  specify  a  channel,  RESTORE  resets  the  DATA  pointer  to 
the  beginning  of  the  DATA  sequence. 

2.  RESTORE  affects  only  the  current  program  unit.  Thus,  executing 
a  RESTORE  statement  in  a  subprogram  does  not  affect  the  DATA 
pointer  in  the  main  program. 

3.  If  there  is  no  channel  specified,  and  the  program  has  no  DATA 
statements,  RESTORE  has  no  effect. 

4.  The  file  specified  by  chnl-exp  must  be  open. 

5.  If  chnl-exp  specifies  a  magnetic  tape  file,  BASlC-PLUS-2  rewinds  the 
tape  to  the  first  record  in  the  file. 

6.  The  KEY  clause  applies  to  indexed  files  only.  It  sets  a  new  key  of 
reference  equal  to  int-exp  and  sets  the  next  record  pointer  to  the  first 
logical  record  in  that  key. 
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7.  For  indexed  files,  the  RESTORE  statement  without  a  KEY  clause  sets 
the  next  record  pointer  to  the  first  logical  record  specified  by  the 
current  key  of  reference.  If  there  is  no  current  key  of  reference,  the 
RESTORE  statement  sets  the  next  record  pointer  to  the  first  logical 
record  of  the  primary  key. 

8.  If  you  use  the  RESTORE  statement  on  any  file  type  other  than  in¬ 
dexed,  BASIC-PLUS-2  sets  the  next  record  pointer  to  the  first  record 
in  the  file. 

9.  The  RESTORE  statement  is  not  allowed  on  virtual  array  files  or  on 
files  opened  on  unit  record  devices. 


Example 


200  RESTORE  *7%,  KEY  «4X 
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RESUME 

The  RESUME  statement  marks  an  exit  point  from  an  ON  ERROR  error¬ 
handling  routine.  BASIC-PLUS-2  clears  the  error  condition  and  returns 
program  control  to  a  specified  line  number  or  label,  or  to  the  program 
block  in  which  the  error  occurred. 


Format 

RESUME  [target] 


Syntax  Rules 

Target  must  be  a  valid  BASIC-PLUS-2  line  number  or  label  and  must  exist 
in  the  same  program  unit. 


Remarks 


1.  The  following  restrictions  apply: 

•  The  RESUME  statement  cannot  be  used  in  a  multi-line  DEE  unless 
the  target  is  also  in  the  DEE  function  definition. 

•  The  execution  of  a  RESUME  with  no  target  is  illegal  if  there  is  no 
error  active. 

•  A  RESUME  statement  cannot  transfer  control  out  of  the  current 
program  unit.  Therefore,  a  RESUME  statement  with  no  target 
cannot  terminate  an  error  handler  if  the  error  handler  is  haiidling 
an  error  that  occurred  in  a  subprogram  or  an  external  function, 
and  the  error  was  passed  to  the  calling  program's  error  handler  by 
an  ON  ERROR  GO  BACK  statement  or  by  default. 

2.  When  no  target  is  specified  in  a  RESUME  statement,  BASIC-PLUS-2 
transfers  control  based  on  where  the  error  occurs.  If  the  error  occurs 
on  a  numbered  line  containing  a  single  statement, 

BASIC-PLUS-2  always  transfers  control  to  that  statement.  When 
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the  error  occurs  within  a  multi-statement  line  under  the  following 
conditions,  BASIC-PLUS-2  acts  as  follows: 

•  Within  a  FOR,  WHILE,  or  UNTIL  loop,  BASIC-PLUS-2  transfers 
control  to  the  first  statement  that  follows  the  FOR,  WHILE,  or 
UNTIL  statement. 

•  Within  a  SELECT  block,  BASIC-PLUS-2  transfers  control  to  the 
start  of  the  CASE  block  in  which  the  error  occurs. 

•  After  a  loop  or  SELECT  block,  BASIC-PLUS-2  transfers  control  to 
the  statement  that  follows  the  NEXT  or  END  SELECT  statement. 

•  If  none  of  the  above  conditions  occurs,  BASIC-PLUS-2  transfers 
control  back  to  the  statement  that  follows  the  most  recent  line 
number. 

3.  A  RESUME  statement  with  a  specified  line  number  transfers  control 
to  the  first  statement  of  a  multi-statement  line,  regardless  of  which 
statement  caused  the  error. 

4.  A  RESUME  statement  with  a  specified  label  transfers  control  to  the 
block  of  code  indicated  by  that  label. 

5.  When  BASIC-PLUS-2  executes  a  RESUME  statement,  it  clears  the 
error  condition. 

6.  After  a  CTRL/C  trap,  a  RESUME  statement  with  no  line  number 
returns  control  to  the  statement  immediately  following  the  previous 
line  number. 


Example 


10  Error_routine: 

IF  ERR  *  11 
THEN 

CLOSE  «1 

RESUME  end_of_prog 

ELSE 

RESUME 

END  IF 

end.of.prog:  END 
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RETURN 

The  RETURN  statement  transfers  control  to  the  statement  immediately  fol¬ 
lowing  the  most  recently  executed  GOSUB  or  ON  . .  .  GOSUB  statement 
in  the  current  program  unit. 


Format 

RETURN 


Syntax  Rules 

None. 


Remarks 


1.  Once  the  RETURN  is  executed  in  a  subroutine,  no  other  statements 
in  the  subroutine  are  executed,  even  if  they  appear  after  the  RETURN 
statement. 

2.  Execution  of  a  RETURN  statement  before  the  execution  of  a  GOSUB 
or  ON  .  .  .  GOSUB  causes  BASlC-PLUS-2  to  signal  "RETURN  without 
GOSUB"  (ERR=72). 


Example 

100  GOSUB  subroutine.! 


subrout ine.l : 


RETURN 
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RIGHTS 

The  RIGHTS  function  extracts  a  substring  from  a  string's  right  side, 
leaving  the  string  unchanged. 


Format 

5fM^dr=RIGHT[$]  (str-exp,  int-exp) 

Syntax  Rules 

None. 

Remarks 


1.  The  RIGHTS  function  extracts  a  substring  from  str-exp  and  stores  the 
substring  in  str-var.  The  substring  begins  with  the  character  in  the 
position  specified  hy  int-exp  and  ends  with  the  rightmost  character  in 
the  string. 

2.  The  length  of  the  resulting  string  is  the  number  of  characters  in  str-exp 
minus  int-exp. 

3.  If  int-exp  is  less  than  or  equal  to  zero,  RIGHTS  returns  the  entire 
string. 

4.  If  int-exp  is  greater  than  the  length  of  str-exp,  RIGHTS  returns  a  null 
string. 

5.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  a  WORD  integer. 
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Example 


50  DECLARE  STRING  maln.str,  k 
end.result 

main.str  *  "1234567" 
end.result  «  RIGHT! (main.str »  3) 
PRINT  end.result 

Output 

34567 
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The  RND  function  returns  a  random  number  greater  than  or  equal  to  zero 
and  less  than  1. 


Format 

real-var  =  RND 

Syntax  Rules 

None. 


Remarks 


1.  If  the  RND  function  is  preceded  by  a  RANDOMIZE  statement, 
BASIC-PLUS-2  generates  a  different  random  number  or  series  of 
numbers  each  time  a  program  executes. 

2.  The  RND  function  returns  a  pseudorandom  number  if  not  preceded 
by  a  RANDOMIZE  statement;  that  is,  each  time  a  program  runs, 
BASIC-PLUS-2  generates  the  same  random  number  or  series  of 
random  numbers. 

3.  The  RND  function  returns  a  floating-point  value  of  the  default  size. 
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Example 


40  DECLARE  REAL  random.num 
RANDOMIZE 

FOR  I  s  1  TO  3  IFOR  loop  causes  BASIC  to  print  three  random  numbers 

random_num  *  RND 
PRINT  random.num 

NEXT  I 

Output 

.865243 

.477417 

.734673 
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The  RSET  statement  assigns  right-justified  data  to  a  string  variable.  RSET 
does  not  change  a  string  variable's  length. 


Format 

RSET  str-var,  . . .  =  str-exp 


Syntax  Rules 

None. 


Remarks 


1.  The  RSET  statement  treats  strings  as  fixed-length.  It  does  not  change 
the  length  of  str-var,  nor  does  it  create  new  storage  locations. 

2.  If  str-var  is  longer  than  str-exp,  RSET  right-justifies  the  data  and  pads 
it  with  spaces  on  the  left. 

3.  If  str-var  is  shorter  than  str-exp,  RSET  truncates  str-exp  on  the  left. 

4.  With  string  virtual  arrays,  RSET  changes  the  length  of  str-exp  to  the 
declared  length  by  padding  it  with  spaces  on  the  right.  Note  that  the 
LET  statement  uses  null  characters  for  padding. 


Example 


20  DECLARE  STRING  test 
test  =  "ABODE" 

RSET  test  =  "123" 
PRINT  "X"  ♦  test 

Output 

X  123 
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SCRATCH 


The  SCRATCH  statement  deletes  the  current  record  and  all  following 
records  in  a  sequential  file. 


Format 

SCRATCH  #chnl-exp 


Syntax  Rules 

Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  associated  with  a 
file.  It  must  be  immediately  preceded  by  a  number  sign  ( # ). 


Remarks 


1.  The  SCRATCH  statement  applies  to  ORGANIZATION  SEQUENTIAL 
files  only. 

2.  Before  you  execute  the  SCRATCH  statement,  the  file  must  be  opened 
with  ACCESS  SCRATCH. 

3.  The  SCRATCH  statement  has  no  effect  on  terminals  or  unit  record 
devices. 

4.  For  disk  files,  the  SCRATCH  statement  discards  the  current  record  and 
all  that  follows  it  in  the  file.  The  physical  length  of  the  file  does  not 
change. 

5.  For  magnetic  tape  files,  the  SCRATCH  statement  overwrites  the 
current  record  with  two  end-of-file  marks. 


Example 


600  SCRATCH  *4% 
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SEG$ 


The  SEG$  function  extracts  a  substring  from  a  main  string,  leaving  the 
original  string  unchanged. 


Format 

str-var  =  SEG$(str-exp,  int-expl,  int-exp2l 

Syntax  Rules 

None. 


Remarks 


1.  BASIC -PLUS-2  extracts  the  substring  from  str-exp,  the  main  string, 
and  stores  the  substring  in  str-var.  The  substring  begins  with  the 
character  in  the  position  specified  by  int-expl  and  ends  with  the 
character  in  the  position  specified  by  int-expl. 

2.  If  int-expl  is  less  than  1,  BASIC-PLUS-2  assumes  a  value  of  1. 

3.  If  int-expl  is  greater  than  int-expl  or  the  length  of  str-exp,  the  SEG$ 
function  returns  a  null  string. 

4.  If  int-expl  equals  int-expl,  the  SEG$  function  returns  the  character  at 
the  position  specified  by  int-expl. 

5.  Unless  int-expl  is  greater  than  the  length  of  str-exp,  the  length  of  the 
returned  substring  equals  int-expl  minus  int-expl  plus  1.  If  int-expl 
is  greater  than  the  length  of  str-exp,  the  SEG$  function  returns  all 
characters  from  the  position  specified  by  int-expl  to  the  end  of  str-exp. 

6.  If  you  specify  a  floating-point  expression  for  int-expl  or  int-expl, 
BASIC-PLUS-2  truncates  it  to  WORD  integer. 
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Example 


10  DECLARE  STRING  alpha,  center 
alpha  «  "ABCDEFGHIJK" 
center  «  SEG$ (alpha,  4,  8) 
PRINT  center 

Output 

DEFGH 
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SELECT 

The  SELECT  statement  lets  you  specify  an  expression,  a  number  of 
possible  values  the  expression  may  have,  and  a  number  of  alternative 
statement  blocks  to  be  executed  for  each  possible  case. 


Format 

SELECT  expl 

case-clause 


[  else-clause  ] 

END  SELECT 

case-clause:  CkSEcase-item,  . . . 
[  statement  ]  . . . 


case-item:  (  a  r  cm  a  \ 

I  exp3  TO  exp4  [  ,exp5  TO  expB  ] ,  . . .  / 

else-clause:  CASE  ELSE 

[  statement  J  . . . 
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Syntax  Rules 

1.  Expl  is  the  expression  to  be  tested  against  the  case-clauses  and  the 
else<lau$e.  It  can  be  numeric  or  string. 

2.  Case-clause  consists  of  the  CASE  keyword  followed  by  a  case-item  and 
statements  to  be  executed  when  the  case-item  is  true. 

3.  Else-clause  consists  of  the  CASE  ELSE  keywords  followed  by  state¬ 
ments  to  be  executed  when  no  previous  case-item  has  been  selected  as 
true. 

4.  Case-item  is  either  an  expression  to  be  compared  with  expl  or  a  range 
of  values  separated  with  the  keyword  TO. 

•  Rel-op  is  a  relational  operator  specifying  how  expl  is  to  be  com¬ 
pared  to  expl.  If  you  do  not  include  a  rel-op,  BASIC-PLUS-2 
assumes  the  equals  (=)  operator.  BASIC-PLUS-2  executes  the 
statements  in  the  CASE  block  when  the  specified  relational 
expression  is  true. 

•  Exp3  and  exp4  specify  a  range  of  numeric  or  string  values  sepa¬ 
rated  by  the  keyword  TO.  Multiple  ranges  must  be  separated  with 
commas.  BASIC-PLUS-2  executes  the  statements  in  the  CASE 
block  when  expl  falls  within  any  of  the  specified  ranges. 

5.  A  SELECT  statement  can  have  only  one  else-clause.  The  else-clause 
is  optional  and,  when  present,  must  be  the  last  CASE  block  in  the 
SELECT  block. 

6.  The  SELECT  statement  begins  the  SELECT  BLOCK  and  the  END 
SELECT  keywords  terminate  it.  BASIC-PLUS-2  signals  an  error  if  you 
do  not  include  the  END  SELECT  keywords. 

7.  Each  CASE  keyword  establishes  a  CASE  block.  The  next  CASE  or 
END  SELECT  keyword  ends  the  CASE  block. 

8.  You  can  nest  SELECT  blocks  within  a  CASE  or  CASE  ELSE  block. 
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Remarks 


1.  Each  statement  in  a  SELECT  block  can  have  its  own  line  number. 

2.  BASIC-PLUS-2  evaluates  expl  when  the  SELECT  statement  is  first 
encountered;  BASIC-PLUS-2  then  compares  expl  with  each  case-clause 
in  order  of  occurrence  until  a  match  is  found  or  until  a  CASE  ELSE 
block  or  END  SELECT  is  encountered. 

3.  The  following  conditions  constitute  a  match: 

•  Expl  satisfies  the  relationship  to  expl  specified  by  r el-op, 

•  Expl  is  greater  than  or  equal  to  exp3  but  less  than  or  equal  to  exp4, 
greater  than  or  equal  to  exp5  but  less  than  or  equal  to  exp6,  and  so 
on. 

4.  When  a  match  is  found  between  expl  and  a  case-item,  BASIC-PLUS-2 
executes  the  statements  in  the  CASE  block  where  the  match  occurred. 
If  ranges  overlap,  the  first  match  causes  BASIC-PLUS-2  to  execute 
the  statements  in  the  CASE  block.  After  executing  CASE  block 
statements,  control  passes  to  the  statement  immediately  following  the 
END  SELECT  keywords. 

5.  If  no  CASE  match  occurs,  BASIC-PLUS-2  executes  the  statements  in 
the  else-clause,  if  present,  and  then  passes  control  to  the  statement 
immediately  following  the  END  SELECT  keywords. 

6.  If  no  CASE  match  occurs  and  you  do  not  supply  a  case-else  clause, 
control  passes  to  the  statement  following  the  END  SELECT  keywords. 


Example 


100  SELECT  A%  ♦  +  C% 

CASE  »  100 

PRINT  'THE  VALUE  IS  EXACTLY  100' 

CASE  1  TO  99 

PRINT  'THE  VALUE  IS  BETWEEN  1  AND  99' 
CASE  >  100 

PRINT  'THE  VALUE  IS  GREATER  THAN  100' 
CASE  ELSE 

PRINT  'THE  VALUE  IS  LESS  THAN  1' 

END  SELECT 


Statements  and  Functions  4-285 


SET  [MO]  PROMIPT 


SET  [MO]  PROMPT 

The  SET  PROMPT  statement  enables  a  question  mark  prompt  to  appear 
after  BASIC-PLUS-2  executes  either  an  INPUT,  LINPUT,  INPUT  LINE, 
MAT  INPUT,  or  MAT  LINPUT  statement  on  channel  #0.  The  SET  NO 
PROMPT  statement  disables  the  question  mark  prompt. 


Format 

SET  [NO]  PROMPT 


Syntax  Rules 

None. 


Remarks 


1.  If  you  do  not  specify  a  SET  PROMPT  statement,  the  default  is  SET 
PROMPT. 

2.  SET  NO  PROMPT  disables  BASIC-PLUS-2  from  issuing  a  question 
mark  prompt  for  the  INPUT,  LINPUT,  INPUT  LINE,  MAT  INPUT, 
and  MAT  LINPUT  statements  on  channel  #0. 

3.  Prompting  is  reenabled  when  either  a  SET  PROMPT  statement  or 
a  CHAIN  statement  is  executed,  or  when  a  NEW,  OLD,  RUN  or 
SCRATCH  command  is  executed  in  the  BASIC  environment. 

4.  The  SET  NO  PROMPT  statement  does  not  affect  the  string  constant 
you  specify  as  the  input  prompt  with  the  INPUT  statement. 
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Example 


20  DECLARE  STRING  your .name,  your.age,  your_grade 
INPUT  "Enter  your  name" ;your_name 
SET  NO  PROMPT 

INPUT  "Enter  your  age" ;your.age 
SET  PROMPT 

INPUT  "Enter  the  last  school  grade  you  completed" ; your .grade 

Output 

Enter  your  name?  Katherine  Kelly 
Enter  your  age? 15 

Enter  the  last  school  grade  you  completed?  9 
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SGiy 

The  SGN  function  determines  whether  a  numeric  expression  is  positive, 
negative,  or  zero.  It  returns  a  1  if  the  expression  is  positive,  a  -1  if  the 
expression  is  negative,  and  zero  if  the  expression  is  zero. 

Format 

int-var  =  SQH(real-exp) 

Syntax  Rules 

None. 

Remarks 

1.  If  real-exp  does  not  equal  zero,  SGN  returns  MAG{real-exp)/real-exp. 

2.  If  real-exp  equals  zero,  SGN  returns  a  value  of  zero. 

3.  SGN  returns  a  WORD  integer. 

Example 

10  DECLARE  INTEGER  sign 
sign  -  SGN (46/23) 
PRINT  sign 

Output 
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SIN 


The  SIN  function  returns  the  sine  of  an  angle  in  radians. 


Format 

real-var  =  S\U(real-exp} 


Syntax  Rules 

Real-exp  is  an  angle  specified  in  radians. 


Remarks 


1.  The  returned  value  is  between  -1  and  1. 

2.  BASIC-PLUS-2  expects  the  argument  of  the  SIN  function  to  be  a  real 
expression.  When  the  argument  is  a  real  expression,  BASIC-PLUS-2 
returns  a  value  of  the  same  floating-point  size.  When  the  argument 
is  not  a  real  expression,  BASIC-PLUS-2  converts  the  argument  to 
the  default  floating-point  size  and  returns  a  value  of  the  default 
floating-point  size. 


Example 


100  sl.angle  «  SIN (PI/2) 
PRINT  sl.angle 

Output 

1 
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SLEEP 

The  SLEEP  statement  suspends  program  execution  for  a  specified  number 
of  seconds  or  until  a  carriage  return  is  entered  from  the  controlling 
terminal. 

Format 

SLEEP 

int-exp 

Syntax  Rules 

1.  Int-exp  is  the  number  of  seconds  BASIC-PLUS-2  waits  before  resum¬ 
ing  program  execution. 

2.  Int-exp  must  be  an  integer  from  0  through  32767;  if  it  is  greater  than 
32767,  BASIC-PLUS-2  signals  the  error  "Integer  error"  (ERR=51). 

Remarks 

Pressing  the  RETURN  key  on  the  controlling  terminal  cancels  the  effect  of 
the  SLEEP  statement. 

Example 

60  SLEEP  120X 
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SPACES 

The  SPACES  function  creates  a  string  containing  a  specified  number  of 
spaces. 


Format 

str-var  =  SPACES  (int-expj 

Syntax  Rules 

Int-exp  specifies  the  number  of  spaces  in  the  returned  string. 

Remarks 

1.  BASIC-PLUS-2  treats  an  int-exp  less  than  zero  as  zero. 

2.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  a  WORD  integer. 

Example 


10  DECLARE  STRING  A.  B 
A  «  "1234" 

B  *  "6678" 

PRINT  A  +  SPACE! (5%)  ♦  B 

Output 

1234  5678 


Statements  and  Functions  4-291 


SQR 


SQR 


The  SQR  function  returns  the  square  root  of  a  positive  number. 


Format 


Syntax  Rules 


None. 


Remarks 


1.  BASIC-PLUS-2  signals  the  error  "Imaginary  square  roots"  (ERR=54), 
when  real-exp  is  negative  and  returns  the  square  root  of  the  absolute 
value  of  the  expression. 

2.  BASIC-PLUS-2  assumes  that  the  argument  of  the  SQR  function  is  a 
real  expression.  When  the  argument  is  a  real  expression, 
BASIC-PLUS-2  returns  a  value  of  the  same  floating-point  size.  When 
the  argument  is  not  a  real  expression,  BASIC-PLUS-2  returns  a  value 
of  the  default  floating-point  size. 


Example 


100  DECLARE  REAL  root 


root  *  SQR(20*5) 
PRINT  root 


Output 

10 
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STATUS 

The  STATUS  function  returns  a  word-length  integer  value  containing 
information  about  the  last  opened  channel.  Your  program  can  test  each 
bit  to  determine  the  status  of  the  channel. 


Format 

//7f-rar  =  STATUS 


Syntax  Rules 

None. 


Remarks 


1.  The  STATUS  function  returns  a  WORD  integer. 

2.  The  value  returned  by  the  STATUS  function  is  undefined  until 
BASIC-PLUS-2  executes  an  OPEN  statement. 

3.  The  STATUS  value  is  reset  by  every  input  operation  on  any  channel. 
Therefore,  you  should  copy  the  STATUS  value  to  a  different  storage 
location  before  your  program  executes  another  input  operation. 

4.  On  RSTS/E  systems,  depending  on  the  error,  the  STATUS  function 
displays  a  value  representing  one  of  the  following: 

•  The  RMS- 11  primary  status  field  (STS)  or  the  RMS- 11  secondary 
status  field  (STV).  See  the  RSTS/E  RMS-ll  MACRO  Programmer's 
Guide  for  more  information. 

•  The  device  characteristics  after  an  RMS- 11  OPEN  file  operation 
(set  by  the  DEV  field  of  the  FAB).  See  the  RSTS/E  RMS-ll  MACRO 
Programmer's  Guide  system  for  more  information. 

•  For  OPEN  operations  where  no  error  occurs,  the  status  word 
describes  the  device  characteristics  of  the  FIRQB  and  FQFLAG 
field.  The  first  7  bits  describe  the  device,  and  bits  7  through  15 
describe  characteristics  of  the  OPEN  statement.  See  the 
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BASIC-PLUS  Language  Manual  or  the  RSTS/E  System  Directives 
Manual  for  more  information  on  STATUS  values. 

5.  On  RSX  systems,  depending  on  the  error,  the  STATUS  function 

displays  a  value  representing  one  of  the  following: 

•  The  RMS- 11  primary  status  field  (STS)  or  the  RMS- 11  secondary 
status  field  (STV).  See  the  RSX-llM/M-PLUS  RMS-11  Macro 
Programmer's  Guide  for  more  information. 

•  The  device  characteristics  after  an  RMS- 11  OPEN  file  operation 
(set  by  the  DEV  field  of  the  FAB).  See  the  RSX-llM/M-PLUS 
RMS-11  Macro  Programmer's  Guide  for  more  information. 

•  In  the  event  of  a  directive  error,  the  Directive  Status  Word  ($DSW) 
and  its  corresponding  error  code.  See  the  RSX-llM/M-PLUS  Mini 
Reference  for  the  error  codes. 

•  The  STATUS  field  of  a  QIO.  See  the  RSX-llM/M-PLUS  I/O 
Drivers  Reference  Manual  for  more  information. 

•  The  first  word  of  a  GETLUN  or  GLUN$  directive  describing 
device  characteristics.  See  the  RSX-llM/M-PLUS  and  Micro /RSX 
Executive  Reference  Manual  for  more  information. 

See  Table  4-7  for  a  list  of  the  values  of  the  STATUS  word  for 

OPEN  operations  where  no  errors  occur. 
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Table  4-7:  RSX  STATUS  Values 


Value 

Bit  Set 

Meaning 

1 

0 

Record-oriented  device 

2 

1 

Carriage-control  device 

4 

2 

Terminal  device 

8 

3 

Directory  device 

16 

4 

Single-directory  device 

32 

5 

Sequential  device 

64 

6 

Mass  storage  device 

128 

7 

User-mode  diagnostics  supported 

256 

8 

Massbus  device 

512 

9 

Unit  software  write-locked 

1024 

10 

Input  spooled  device 

2048 

11 

Output  spooled  device 

4096 

12 

Pseudo  device 

8192 

13 

Device  mountable  as  a  communication 

16384 

14 

Device  mountable  as  a  Files- 11  device 

-32768 

15 

Device  mountable 

Example 

160  YX  -  STATUS 
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STOP 

The  STOP  statement  halts  program  execution  allowing  you  to  optionally 
continue  execution. 


Format 

STOP 


Syntax  Rules 

None. 


Remarks 


1.  The  STOP  statement  cannot  appear  before  a  PROGRAM,  SUB,  or 
FUNCTION  statement. 

2.  The  STOP  statement  does  not  close  files. 

3.  When  a  STOP  statement  executes  in  a  program  executed  with  the 
environment  RUN /DEBUG  command  or  compiled  with  the  /DEBUG 
qualifier,  control  passes  to  the  BASIC-PLUS-2  debugger.  The  de¬ 
bugger  prints  the  line  number  and  module  name  associated  with  the 
STOP  statement,  then  displays  the  number  sign  (#)  prompt.  You 
can  then  use  the  BASIC-PLUS-2  debugger  commands  to  analyze  and 
debug  your  program.  See  Appendix  B  for  a  description  of  the 
BASIC-PLUS-2  debugger  commands.  Once  you  are  finished  debug¬ 
ging  your  program,  use  the  EXIT  command  to  exit  from  the  debugger 
and  end  the  program. 

4.  When  a  STOP  statement  executes  in  a  program  executed  with  the 
RUN  command  or  compiled  without  the  /DEBUG  qualifier,  the  line 
number  of  the  STOP  statement  and  a  number  sign  (#)  prompt  are 
printed.  In  response  to  the  prompt,  you  can  either  type  the  debugger 
command  CONTINUE  to  continue  program  execution,  or  the  EXIT 
command  to  end  the  program.  The  EXIT  command  closes  all  files 
before  leaving  the  program. 
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Example 


40  PRINT  "Type  CONTINUE  when  the  program  stops" 
INPUT  "Do  you  want  to  stop  now" ;  Quit# 

IF  Quit!  *  "Y" 

THEN 

STOP 

ELSE 

PRINT  "So  what  are  you  waiting  lor?" 
STOP 

END  IF 

Output 

Type  CONTINUE  when  the  program  stops 
Do  you  want  to  stop  now?  Y 
Stop  at  line  40 

#  CONTINUE 

BASIC2 
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STR$ 

The  STR$  function  changes  a  numeric  expression  to  a  numeric  character 
string  without  leading  and  trailing  spaces. 


Format 

str-var  =  (num-expj 


Syntax  Rules 

None. 


Remarks 


1.  If  num-exp  is  negative,  the  first  character  in  the  returned  string  is  a 
minus  sign  ( - ). 

2.  The  STR$  function  produces  E  notation. 

3.  When  you  print  a  floating-point  number  that  has  6  decimal  digits 
or  more  but  the  integer  portion  has  6  digits  or  less  (for  example, 
1234.567),  BASIC-PLUS-2  rounds  the  number  to  6  digits  (1234.57). 

If  a  floating-point  number's  integer  part  is  7  decimal  digits  or  more, 
BASIC-PLUS-2  rounds  the  number  to  6  digits  and  prints  it  in  E  format. 

4.  When  you  print  a  floating-point  number  with  magnitude  between  0.1 
and  1,  BASIC-PLUS-2  rounds  it  to  6  digits.  When  you  print  a  number 
with  magnitude  smaller  than  0.1,  BASIC-PLUS-2  rounds  it  to  6  digits 
and  prints  it  in  E  format. 


4-298  Statements  and  Functions 


O 


STR$ 


Example 


100  DECLARE  STRING  new.num 
new.num  *  STR$( 1543. 669) 
PRINT  new.nim 

Output 

1543.66 


Statements  and  Functions  4-299 


STRINGS 


STRIMG$ 


The  STRINGS  function  creates  a  string  containing  a  specified  number  of 
identical  characters. 


Format 

sfr-i^ar  =  STRING$^//jf-exp/,  int-exp2) 

Syntax  Rules 

1.  Int-expl  specifies  the  character  string's  length. 

2.  Int-expl  is  the  decimal  ASCII  value  of  the  character  that  makes  up  the 
string.  This  value  is  treated  modulo  256. 


Remarks 


1.  BASIC-PLUS-2  signals  the  error  "Integer  error"  (ERR=51),  if  int-expl  is 
greater  than  32767. 

2.  If  int-expl  is  less  than  or  equal  to  zero,  BASIC-PLUS-2  treats  it  as 
zero. 

3.  BASIC-PLUS-2  treats  int-expl  as  an  unsigned  8-bit  integer.  For 
example,  -1  is  treated  as  255. 

4.  If  either  int-expl  or  int-expl  is  a  floating-point  expression, 
BASIC-PLUS-2  truncates  it  to  a  WORD  integer. 
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Exam|il« 


40  DECLARE  STRING  output.str 

output.«tr  -  STRING! (loX.  60X)  !50  is  the  ASCII  value  ol  the 

PRINT  output.str  ! character  "2" 

Output 

2222222222 


Statements  and  Functions  4-301 


SUB 


SUB 


The  SUB  statement  marks  the  beginning  of  a  BASIC-PLUS-2  subprogram 
and  specifies  the  number  and  data  type  of  its  parameters. 


Format 

SUB  sub-name  [  ( formal-param,  ...}][  statement  ]  . . . 
[  statement  ]... 

f  END  SUB  \ 

\  SUBEND  j 


formal-param:  [  data-type  ]  < 

'  unsubs-var 

array-name  ( 

■  int-const  ' 

> 

,  .  .  .  j 

< 

.  f 

■  ■  ■ 

Syntax  Rules 


1.  The  SUB  statement  must  be  the  first  statement  in  the  SUB  subprogram. 

2.  Sub-name  is  the  name  of  the  separately  compiled  subprogram. 

3.  Formal-param  specifies  the  number  and  type  of  parameters  for  the 
arguments  the  SUB  subprogram  expects  to  receive  when  invoked. 

•  Empty  parentheses  indicate  that  the  SUB  subprogram  has  no 
parameters. 

•  Data-type  specifies  the  data  type  of  a  parameter.  If  you  do  not 
specify  a  data  type,  parameters  are  of  the  default  data  type  and 
size.  When  you  do  specify  a  data  type,  all  following  parameters 
are  of  that  data  type  until  you  specify  a  new  data  type.  Data 
type  keywords  and  their  size,  range,  and  precision  are  listed  in 
Table  1-2  in  this  manual. 
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4.  Sub-name  can  have  from  one  through  six  characters  and  must  conform 
to  the  following  rules: 

•  The  first  character  of  an  unquoted  name  must  be  an  alphabetic 
character  (A  through  Z).  The  remaining  characters,  if  present,  can 
be  any  combination  of  letters,  digits  (0  through  9),  dollar  signs 

( $ ),  or  periods  ( . ). 

•  A  quoted  name  can  consist  of  any  combination  of  alphabetic 
characters,  digits,  dollar  signs  ( $ ),  periods  ( . ),  or  spaces. 

5.  Parameters  defined  in  fomal-param  must  agree  in  number,  type,  and 
ordinality  with  the  arguments  specified  in  the  CALL  statement  of  the 
calling  program. 

6.  You  can  specify  up  to  32  formal  parameters.  MACRO-11  subprograms 
accept  a  maximum  of  255  parameters. 

7.  Each  SUB  statement  must  have  a  corresponding  END  SUB  statement 
or  SUBEND  statement. 


Remarks 


1.  Compiler  directives  and  comment  fields  created  with  an  exclamation 
point  (!)  can  precede  the  SUB  statement  because  they  are  not 
BASlC-PLUS-2  stateinents.  Note  that  REM  is  a  BASIC-PLUS-2 
statement;  therefore,  it  cannot  precede  the  SUB  statement. 

2.  Any  BASIC-PLUS-2  statement  except  the  FUNCTION  statement  can 
appear  in  a  SUB  subprogram. 

3.  All  variables,  except  those  named  in  MAP  and  COMMON  statements, 
are  local  to  that  subprogram. 

4.  BASIC-PLUS-2  initializes  local  variables  to  zero  or  the  null  string. 

5.  In  BASIC-PLUS-2  you  cannot  specify  how  subprograms  receive  pa¬ 
rameters.  BASIC-PLUS-2  subprograms  receive  numeric  unsubscripted 
variables  by  reference  and  string  unsubscripted  variables  by  descrip¬ 
tor.  Table  4-1  lists  and  describes  BASIC-PLUS-2  parameter-passing 
mechanisms. 

•  BY  REF  specifies  that  the  subprogram  receives  the  argument's 
address. 

•  BY  DESC  specifies  that  the  subprogram  receives  the  address  of 
a  BASIC-PLUS-2  descriptor.  For  information  about  the  format 
of  a  BASIC-PLUS-2  descriptor  for  strings  and  arrays,  see  the 
BASIC-PLUS-2  User's  Guide. 
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6.  You  cannot  call  subprograms  recursively. 

7.  The  default  error  handling  for  SUB  subprogams  is  ON  ERROR  GO 
BACK. 


Example 

100  SUB  SOBPBO  (BYTE  AGE.  DOUBLE  WAGE(20.20),  STRING  EMP.NAME) 

000  END  SUB 
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SUBEND - 

The  SUBEND  statement  is  a  synonym  for  END  SUB.  See  the  END  state¬ 
ment  for  more  information. 


Format 

SUBEND 
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SUBEXIT 


The  SUBEXIT  statement  is  a  synonym  for  the  EXIT  SUB  statement.  See 
the  EXIT  statement  for  more  information. 


Format 

SUBEXIT 


4-306  Statements  and  Functions 


SUMS 


SUM$ 


The  SUMS  function  returns  a  string  whose  value  is  the  sum  of  two 
numeric  strings. 


Format 

str-var  =  S[iM$(str-exp1,  str-exp2} 


Syntax  Rules 

None. 


Remarks 


1.  Each  string  expression  can  contain  up  to  54  ASCII  digits  and  an 
optional  decimal  point  and  sign. 

2.  BASIC-PLUS-2  adds  sfr-exp2  to  str-expl  and  stores  the  result  in 
str-var. 

3.  If  str-expl  and  str-expl  are  integers,  str-var  takes  the  precision  of  the 
larger  string  unless  trailing  zeros  generate  that  precision. 

4.  If  str-expl  and  str-expl  are  decimal  fractions,  str-var  takes  the  preci¬ 
sion  of  the  more  precise  fraction  unless  trailing  zeros  generate  that 
precision. 

5.  SUMS  omits  trailing  zeros  to  the  right  of  the  decimal  point. 

6.  The  sum  of  two  fractions  takes  precision  as  follows: 

•  The  sum  of  the  integer  parts  takes  the  precision  of  the  larger  part. 

•  The  sum  of  the  decimal  fraction  part  takes  the  precision  of  the 
more  precise  part. 

7.  SUMS  truncates  leading  and  trailing  zeros. 
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Example 


40  DECLARE  STRING  A,  B,  total 
A  -  "46" 

B  «  "87" 

total  -  SUMKA.B) 

PRINT  total 

Output 
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SWAP% 

The  SWAP%  function  transposes  a  WORD  integer's  bytes. 

Format 

int-var  =  SVilkP%(int-exp) 

Syntax  Rules 

None. 

Remarks 

1.  SWAP%  is  a  WORD  function.  BASIC-PLUS-2  evaluates  int-exp  and 
converts  it  to  the  WORD  data  type,  if  necessary. 

2.  BASIC-PLUS-2  transposes  the  bytes  of  int-exp  and  returns  a  WORD 
integer. 

Examiri* 


30  DECLARE  INTEGER  word.int 
word_int  «  SWAP%(23) 
PRINT  word_int 

Output 

5888 
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SYS 


The  SYS  function  lets  you  perform  special  I/O  functions,  establish  special 
characteristics  for  a  job,  set  terminal  characteristics,  and  cause  the  monitor 
to  execute  special  operations.  The  SYS  function  can  be  used  on  RSTS/E 
systems  only. 


Format 

str-vbl  SySIstr-expl 


Syntax  Rules 

Str-exp  is  a  RSTS/E  SYS  call  code.  See  the  RSTS/E  Programming  Manual 
for  a  complete  list  of  SYS  call  codes  and  their  meanings. 


Remarks 

None. 


Example 


100  OPEN  User.keyboardI  AS  FILE  #1 

Tmp$  »  SYS(CHR$(118)'*-CHR$(18))  !  Cancel  any  typeahead  from  user 

LINUT  'Enter  the  first  line  of  text ' ;User_lnput$ 
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TAB 


When  used  with  the  PRINT  statement,  the  TAB  function  moves  the  cursor 
or  print  mechanism  to  a  specified  column. 


Format 

str-var  =  lM(int-expl 


Syntax  Rules 

Int-exp  specifies  the  column  number  of  the  cursor  or  print  mechanism. 


Remarks 


1.  The  leftmost  column  position  is  zero. 

2.  If  int-exp  is  less  than  the  current  cursor  position,  the  TAB  function  has 
no  effect. 

3.  The  TAB  function  can  move  the  cursor  or  print  mechanism  only  from 
the  left  to  the  right. 

4.  You  can  use  more  than  one  TAB  function  in  the  same  PRINT 
statement. 

5.  Use  semicolons  to  separate  multiple  TAB  functions  in  a  single  state¬ 
ment.  If  you  use  commas,  BASIC-PLUS-2  moves  to  the  next, print 
zone  before  executing  the  TAB  function. 

6.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  WORD  integer. 
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Example 


200  PRINT  "Number  1";  TAB(15);  "Number  2";  TABOO):  "Number  3" 

Output 

Number  1  Number  2  Number  3 
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TAN 


The  TAN  function  returns  the  tangent  of  an  angle  in  radians. 


Format 

real-var  =  TAN  (real-exp) 

Syntax  Rules 

Real-exp  is  an  angle  specihed  in  radians. 


Remarks 

BASlC-PLUS-2  expects  the  argument  of  the  TAN  function  to  be  a  real 
expression.  When  the  argument  is  a  real  expression,  BASIC-PLUS-2 
returns  a  value  of  the  same  floating-point  size.  When  the  argument  is  not 
a  real  expression,  BASIC-PLUS-2  converts  the  argument  to  the  default 
floating-point  size  and  returns  a  value  of  the  default  floating-point  size. 


Example 


10  tangent  *  TAN (PI/4) 
PRINT  tangent 

Output 

1 
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The  TIME  function  returns  the  time  of  day  (in  seconds)  as  a  floating-point 
number.  On  RSTS/E  systems,  the  TIME  function  can  also  return  process 
CPU  time  and  connect  time. 

Format 

real-var  =  l\tK(int-exp} 

Syntax  Rules 

None. 


Remarks 

1.  The  value  returned  by  the  TIME  function  depends  on  the  value  of 
int-exp. 

2.  If  int-exp  equals  zero,  TIME  returns  the  number  of  seconds  since 
midnight. 

3.  BASIC-PLUS-2  on  RSX  systems  accepts  only  an  argument  of  zero. 

All  other  arguments  to  the  TIME  function  are  undefined  and  cause 
BASIC-PLUS-2  to  signal  "Not  implemented"  (ERR=250). 

4.  BASIC-PLUS-2  on  RSTS/E  systems  accepts  values  0  through  4  and 
returns  values  as  shown  in  Table  4-8.  All  other  arguments  to  the 
TIME  function  are  undefined  and  cause  BASIC -PLUS-2  to  signal  "Not 
implemented"  (ERR=250). 

5.  The  TIME  function  returns  a  floating-point  value  of  the  default  size. 

6.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  a  WORD  integer. 


4-314  Statements  and  Functions 


TIME 


Table  4—8:  TIME  Function  Values 


Argument  Value 

BASIC-PLUS-2  Returns 

0 

The  amount  of  time  elapsed  since  midnight  in  seconds 

1 

The  CPU  time  of  the  current  process  in  tenths  of  a 
second 

2 

The  connect  time  of  the  current  process  in  minutes 

3 

Kilo-core  ticks 

4 

Device  time  in  minutes 

Example 


10  PRINT  TIME(O) 

Output 

49671 
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TIMES 

The  TIMES  function  returns  a  string  displaying  the  time  of  day  in  the  form 
hh:mm  AM,  hh:mm  PM,  or  24-hour  clock. 


Format 

str-m  =  TIME$^//?f-eAip^ 


Syntax  Rules 

1.  Str-var  is  the  time  of  day. 

2..  Int-exp  specifies  the  number  of  minutes  before  midnight. 


Remarks 


1.  If  int-exp  equals  zero,  TIMES  returns  the  current  time  of  day. 

2.  Int-exp  must  be  a  value  between  0  and  1440  or  BASIC-PLUS-2  signals 
an  error. 

3.  The  TIMES  function  uses  either  an  AM/PM  or  24-hour  clock.  The 
type  of  clock  is  an  installation  option. 

4.  On  RSTS/E  systems,  the  clock  type  can  also  be  set  by  the  system 
manager  at  system  start-up  time. 

5.  If  you  specify  a  floating-point  expression  for  int-exp,  BASIC-PLUS-2 
truncates  it  to  a  WORD  integer. 
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Example 


20  DECLARE  STRING  current. time 
current .time  >  TIME$(0) 
PRINT  current.time 

Output 

01:61  PM 
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TRIUI$ 


The  TRM$  function  removes  all  trailing  blanks  and  tabs  from  a  specified 
string. 


Format 

str-var  =  lRNi$(str-exp) 


Syntax  Rules 

None. 


Remarks 

The  returned  str-var  is  identical  to  str-exp,  except  that  it  has  all  the  trailing 
blanks  and  tabs  removed. 


Example 


20  DECLARE  STRING  old.string,  new.string 
old.string  «  "ABCDEFG  " 

new.strlng  *  TRM$(old_8tring) 

PRINT  old_8tring;"XYZ" 

PRINT  new_8tring;"XYZ" 

Output 

ABCDEFG  XYZ 

ABCDEFGXYZ 
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UNLESS 

The  UNLESS  qualiher  modifies  a  statement.  BASIC-PLUS-2  executes  the 
modified  statement  only  if  a  conditional  expression  is  false. 

Format 

statement  UNLESS  cond-exp 

Syntax  Rules 

The  UNLESS  statement  cannot  be  used  on  nonexecutable  statements  or  on 
statements  such  as  SELECT,  IF,  and  DEF  that  establish  a  statement  block. 

Remarks 

BASIC-PLUS-2  executes  the  statement  only  if  cond-exp  is  false  (value 
zero). 

Example 


10  PRINT  "A  DOES  NOT  EQUAL  3"  UNLESS  AX  «  3% 
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UNLOCK 


The  UNLOCK  statement  unlocks  the  current  record  or  bucket  locked  by 
the  last  FIND  or  GET  statement. 


Format 

UNLOCK  #chnl-exp 

Syntax  Rules 

Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number  associ¬ 
ated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 


Remarks 


1.  A  file  must  be  opened  on  the  specified  channel  before  UNLOCK  can 
execute. 

2.  The  UNLOCK  statement  applies  only  to  files  on  disk. 

3.  If  the  current  record  is  not  locked  by  a  previous  GET  or  FIND  state¬ 
ment,  the  UNLOCK  statement  has  no  effect  and  BASIC-PLUS-2  does 
not  signal  an  error. 

4.  The  UNLOCK  statement  does  not  affect  record  buffers. 

5.  After  BASIC-PLUS-2  executes  the  UNLOCK  statement,  you  cannot 
update  or  delete  the  current  record. 

6.  Once  the  UNLOCK  statement  executes,  the  position  of  the  current 
record  pointer  is  undefined. 
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Example 

30  UNLOCK  «10X 
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UNTIL 

The  UNTIL  statement  marks  the  beginning  of  an  UNTIL  loop  or  modifies 
the  execution  of  another  statement. 


Format 

Conditional 

UNTIL  cond-exp 

[  statement  ]... 


NEXT 

Statement  Modifier 

Statement  UNTIL  cond-exp 


Syntax  Rules 


The  UNTIL  statement  cannot  be  used  on  nonexecutable  statements  or  on 
statements  such  as  SELECT,  IF,  and  DEF  that  establish  a  statement  block. 


Remarks 


1.  Conditional 

•  A  NEXT  statement  must  end  the  UNTIL  loop. 

•  BASIC-PLUS-2  evaluates  cond-exp  before  each  loop  iteration.  If 
the  expression  is  false  (value  zero),  BASIC-PLUS-2  executes  the 
loop.  If  the  expression  is  true  (value  nonzero),  control  passes  to 
the  first  executable  statement  after  the  NEXT  statement. 
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2.  Statement  Modifier 

BASIC-PLUS-2  executes  the  statement  repeatedly  until  cond-exp  is 
true. 

Examples 


Example  1 

10  ! Conditional 

UNTIL  A  >=  5 

A  =  A  +  .01 
TOTAL  »  TOTAL  +  1 

NEXT 

Example  2 

10  ! Statement  Modifier 

A  =  A  +  1  UNTIL  A  >«  200 
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UPDATE 


The  UPDATE  statement  replaces  a  record  in  a  file  with  a  record  in  the 
record  buffer.  The  UPDATE  statement  is  valid  on  RMS  sequential,  rela¬ 
tive,  and  indexed  files. 


Format 

UPDATE  #chnl-exp  [ ,  COUNT  int-exp  ] 

Syntax  Rules 

1.  Chnl-exp  is  a  numeric  expression  that  specifies  a  channel  number 
associated  with  a  file.  It  must  be  immediately  preceded  by  a  number 
sign  (#). 

2.  Int-exp  specifies  the  size  of  the  new  record. 


Remarks 


1.  If  int-exp  equals  zero,  the  entire  record  is  written  to  the  file. 

2.  The  file  associated  with  chnl-exp  must  be  a  disk  file  opened  with 
ACCESS  MODIFY. 

3.  Each  UPDATE  statement  must  be  preceded  by  a  successful  GET 
or  FIND  operation  or  BASIC-PLUS-2  signals  ‘No  current  record" 
(ERR=131).  Because  FIND  locates  but  does  not  retrieve  records,  you 
must  specify  a  COUNT  clause  in  the  UPDATE  statement  when  the 
preceding  operation  was  a  FIND.  Int-exp  must  exactly  match  the  size 
of  the  old  record. 

4.  After  an  UPDATE  statement  executes,  there  is  no  current  record 
pointer.  The  next  record  pointer  is  unchanged. 
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5.  The  length  of  the  new  record  must  be  the  same  as  that  of  the  existing 
record  for  all  files  with  fixed-length  records  and  for  all  sequential  files. 
If  the  new  record  is  larger  than  the  existing  record,  BASIC-PLLJS-2 
truncates  the  right  side  of  the  new  record  to  fit  the  existing  record. 

If  the  new  record  is  smaller  than  the  existing  record,  the  file  gets 
corrupted.  If  you  specify  a  COUNT  clause,  the  int-exp  must  match  the 
size  of  the  existing  record. 

6.  For  relative  files  with  variable-length  records,  the  new  record  can  be 
larger  or  smaller  than  the  record  it  replaces. 

•  The  new  record  must  be  smaller  than  or  equal  to  the  maximum 
record  size  set  with  the  MAP  or  RECORDSIZE  clause  when  the 
file  was  opened. 

•  You  must  use  the  COUNT  clause  to  specify  the  size  of  the  new 
record  if  it  is  different  from  that  of  the  record  last  accessed  by  a 
GET  operation  on  that  channel. 

7.  For  indexed  files  with  variable-length  records,  the  new  record  can  be 
larger  or  smaller  than  the  record  it  replaces. 

•  When  an  indexed  file  permits  duplicate  primary  keys,  an  updated 
record  must  be  the  same  length  as  the  old  one. 

•  When  the  program  does  not  permit  duplicate  primary  keys,  the 
new  record  can  be  no  longer  than  the  maximum  record  size 
specified  in  the  MAP  or  RECORDSIZE  clause  when  the  file  was 
opened  and  must  include  at  least  the  primary  key  field. 

8.  An  indexed  file  alternate  key  for  the  new  record  can  differ  from  that 
of  the  existing  record  only  if  the  OPEN  statement  for  that  file  specified 
CHANGES  for  the  alternate  key. 

9.  On  RSTS/E  systems,  you  can  use  the  UPDATE  statement  on  native¬ 
mode  files  opened  with  mode  1  bit  set  (UPDATE  mode). 


Example 


100  UPDATE  #4%,  COUNT  32 
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The  VAL  function  converts  a  numeric  string  to  a  floating-point  value. 


Format 

real-var  =  \IM.(str-exp} 


Syntax  Rules 

Str-exp  can  contain  the  ASCII  digits  0  through  9,  uppercase  E,  a  plus  sign 
(+),  a  minus  sign  (-),  and  a  period  (.). 


Remarks 


1.  The  VAL  function  ignores  spaces  and  tabs. 

2.  If  str-exp  is  null  or  contains  only  spaces  and  tabs,  VAL  returns  a  value 
of  zero. 

3.  The  value  returned  by  the  VAL  function  is  of  the  default  floating-point 
size. 


Example 


10  DECLARE  REAL  real.num 
real.num  «  VAL("990.32") 
PRINT  real.num 

Output 

990.32 
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VAL% 


The  VAL%  function  converts  a  numeric  string  to  an  integer. 


Format 

int-var  =  VM.%(str-exp) 


Syntax  Rules 

Str-exp  can  contain  the  ASCII  digits  0  through  9,  a  plus  sign  (  +  ),  or  a 
minus  sign  (-). 


Remarks 


1.  The  VAL%  function  ignores  spaces  and  tabs. 

2.  If  str-exp  is  null  or  contains  only  spaces  and  tabs,  VAL%  returns  a 
value  of  zero. 

3.  The  value  returned  by  the  VAL%  function  is  an  integer  of  the  default 
size. 


Example 


10  DECLARE  INTEGER  ret.int 
ret_int  «  VALXCTSO") 
PRINT  ret.int 

Output 

789 
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The  WAIT  statement  specifies  the  number  of  seconds  the  program  waits 
for  terminal  input  before  signaling  an  error. 


Format 

WAIT  int-exp 


Syntax  Rules 

Int-exp  must  be  a  number  from  0  through  32767;  if  it  is  greater  than 
32767,  BASIC-PLUS-2  assumes  a  value  of  32767. 


Remarks 


1.  The  WAIT  statement  must  precede  a  GET  operation  to  a  terminal  or 
an  INPUT,  INPUT  LINE,  LINPUT,  MAT  INPUT,  or  MAT  LINPUT 
statement;  otherwise,  it  has  no  effect. 

2.  Int-exp  is  the  number  of  seconds  BASIC-PLUS-2  waits  for  input  before 
signaling  the  error  "Keyboard  wait  exhausted"  (ERR=15). 

3.  After  BASIC-PLUS-2  executes  a  WAIT  statement,  all  input  statements 
wait  the  specified  amount  of  time  before  BASIC-PLUS-2  signals  an 
error. 

4.  WAIT  0  disables  the  WAIT  statement. 
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Example 


10  DECLARE  STRING  your.name 
WAIT  60 

INPUT  "You  have  sixty  seconds  to  type  your  name"; your  name 
WAIT  0 


Output 

You  have  sixty  seconds  to  type  your  name? 
^Keyboard  wait  exhausted  at  line  10  in  "WAIT  " 
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WHILE 


The  WHILE  statement  marks  the  beginning  of  a  WHILE  loop  or  modifies 
the  execution  of  another  statement. 


Format 

Conditional 

WHILE  cond-exp 

[  statement  ]... 


NEXT 

Statement  Modifier 

Statement  WHILE  cond-exp 


Syntax  Rules 

1.  Cond-exp  can  be  any  valid  relational  or  logical  expression. 

2.  A  NEXT  statement  must  end  the  WHILE  loop. 

3.  The  WHILE  statement  cannot  be  used  on  nonexecutable  statements  or 
on  statements  such  as  SELECT,  IF,  and  DEF  that  establish  a  statement 
block. 
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Remarks 


Examples 


1.  Conditional 

BASIC-PLUS-2  evaluates  cond-exp  before  each  loop  iteration  If 
the  expression  is  true  (value  nonzero),  BASIC-PLUS-2  executes  the 
oop.  If  the  expression  is  false  (value  zero),  control  passes  to  the  first 
executable  statement  after  the  NEXT  statement. 

2.  Statement  Modifier 

BASIC-PLUS-2  executes  the  statement  repeatedly  as  lone  as  cond-exp 
IS  true.  JO  f 


Example  1 

10  ! Conditional 

WHILE  X  <  100 

X  •  X  +  SqR(X) 

NEXT 

Example  2 

10  ! statement  Modifier 

XX  »  XX  ♦  IX  WHILE  XX  <  lOOX 
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XLATES 


XLATE$ 


The  XLATES  function  translates  one  string  to  another  by  referencing  a 
table  string  you  supply. 


Format 

str-var  =  mJi[$]  (str-exph  str-exp2) 


Syntax  Rules 

1.  Str-expl  is  the  input  string. 

2.  Str-expl  is  the  table  string. 


Remarks 


1. 


2. 


3. 


Str-expl  can  contain  up  to  256  ASCII  characters,  numbered  froin  0 
to  255;  the  position  of  each  character  in  the  string  corresponds  to  an 
ASCII  value.  Because  0  is  a  valid  ASCII  value  (null),  the  first  position 
in  the  table  string  is  position  zero. 

XLATES  scans  str-expl  character  by  character,  from  left  to  right.  It 
finds  the  ASCII  value  n  of  the  first  character  in  str-expl  and  extracts 
the  character  it  finds  at  position  n  in  str-expl.  XLATES  then  appends 
the  character  from  str-expl  to  str-var.  XLATES  continues  this  process, 
character  by  character,  until  the  end  of  str-expl  is  reached. 

The  output  string  may  be  smaller  than  the  input  string  for  the  follow¬ 
ing  reasons: 

•  XLATES  does  not  translate  nulls.  If  the  character  at  position  n 
in  str-expl  is  a  null,  XLATES  does  not  append  that  character  to 

str-var. 

•  If  the  ASCII  value  of  the  input  character  is  outside  the  range  of 
positions  in  str-expl,  XLATES  does  not  append  any  character  to 
str-var. 
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XLATE$ 


Example 


10  DECLARE  STRING  A,  table,  source 
A  *  "abcdefghijklmnopqrstuvwxyz" 
table  >  STRING#  (65,  0)  A 

LINPUT  "Type  a  string  of  uppercase  letters";  source 
PRINT  XLATEl (source,  table) 

Output 

Type  a  string  of  uppercase  letters?  ABCDEFG 
abcdefg 
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Appendix  A 

BASIC-PLUS-2  Keywords 


This  appendix  contains  a  list  of  the  BASIC-PLUS-2  reserved  and  unre¬ 
served  keywords  as  well  as  a  list  of  keywords  that  are  reserved  in 
VAX  BASIC. 


A.1  BASIC-PLUS-2  Reserved  and  Unreserved  Keywords 

The  following  is  a  list  of  the  BASIC-PLUS-2  keywords.  Most  of  the 
keywords  are  reserved.  The  unreserved  keywords  are  marked  with  a 
dagger.  If  you  use  a  reserved  keyword  as  a  program  variable,  you  receive 
an  error  message.  You  can  use  unreserved  keywords  as  program  variables. 

%ABORT 

%CDD 

%CROSS 

%ELSE 

%END 

%FROM 

%IDENT 

%IF 

%INCLUDE 

%LET 

%LIBRARY 

%LIST 

%NOCROSS 

%NOLIST 

%PAGE 

%PRINT 

%SBTTL 

%THEN 
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%TITLE 

%VARIANT 

ABORT 

ABS 

ABS% 

ACCESS 

ACCESS% 

ACTIVE 

ALIGNED 

ALLOW 

ALTERNATE 

AND 

ANY 

APPEND 

AS 

ASC 

ASCII 

ATN 

ATN2 

BACK 

BASE 


# 


BEL 

BINARY 

BIT 


BLOCK 

BLOCKSIZE 

BS 

BUCKETSIZE 

BUFFER 

BUFSIZ 

BY 

BYTE 

CALL 

CASE 

CAUSE 

CCPOS 

CHAIN 

CHANGE 

CHANGES 

CHECKING 

CHR$ 

CLK$ 

CLOSE 

CLUSTERSIZE 

COM 
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COMMON 

COMP% 

CON 

CONNECT 

CONSTANT 

CONTIGUOUS 

CONTINUE 

COS 

COT 

COUNT 

CR 

CTRLC 

CVTF$ 

CVT$F 

CVT$$ 

CVT$% 

CVT%$ 

DAT 

DAT$ 

DATA 

DATE$ 

DECIMAL 

DECLARE 

DEF 

DEFAULTNAME 

DEL 

DELETE 

DESC 

DET 

DIF$ 

DIM 

DIMENSION 

DOUBLE 

DOUBLEBUF 

DUPLICATES 

DYNAMIC 

ECHO 

EDIT$ 

ELSE 

END 

EQ 

EQV 

ERL 

ERN$ 

ERR 
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ERROR 

ERT$ 

ESC 

EXIT 

EXP 

EXPLICIT 

EXTEND 

EXTENDSIZE 

EXTERNAL 

EXTRACT 

FF 

FIELD 

FILE 

FILESIZE 

FILL 

FILLS 

FILL% 

FIND 

FIX 

FIXED 

FLUSH 

FNAMES 

FNEND 

FNEXIT 

FOR 

FORMATS 

FORTRAN 

FREE 

FROM 

FSPS 

FSSS 

FUNCTION 

FUNCTIONEND 

FUNCTIONEXIT 

GE 

GET 

GETRFA 

GFLOAT 

GO 

GOBACK 

GOSUB 

GOTO 

GROUP 

GT 

HFLOAT 
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HT 

IDN 

IF 

IFEND 

IFMORE 

IMAGE 

IMP 

INACTIVE 

INDEXED 

INPUT 

INSTR 

INT 

INTEGER 

INV 

INVALID 

ITERATE 

KEY 

KILL 

LEFT 

LEFTS 

LEN 

LET 

LF 

LINE 

LINO 

LINPUT 

LIST 

LOC 

LOCKED 

LOG 

LOGIO 

LONG 

LSET 

MAG 

MAGTAPE 

MAP 

MAR 

MAR% 

MARGIN 

MAT 

MAX 

MID 

MID$ 

MIN 

MOD 
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MOD% 

MODE 

MODIFY 

MOVE 

NAME 

NEXT 

NO  t 

NOCHANGES 

NODATA 

NODUPLICATES 

NOECHO 

NOEXTEND 

NOMARGIN 

NONE 

NOPAGE 

NOREWIND 

NOSPAN 

NOT 

NUL$ 

NUM 

NUM$ 

NUM1$ 

NUM2 

ON 

ONECHR 

ONERROR 

OPEN 

OPTION 

OR 

ORGANIZATION 

OTHERWISE 

OUTPUT 

OVERFLOW 

PAGE 

PEEK 

PI 

PLACE$ 

POS 

POS% 

PPS% 

PRIMARY 

PRINT 

PROD$ 


t  Unreserved  keyword. 
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PROGRAM 
PROMPT  t 
PUT 
QUO$ 

RAD$ 

RANDOM 

RANDOMIZE 

RCTRLC 

RCTRLO 

READ 

REAL 

RECORD 

RECORDSIZE 

RECORDTYPE 

RECOUNT 

REF 

REGARDLESS 

RELATIVE 

REM 

REMAP 

RESET 

RESTORE 

RESUME 

RETURN 

RFA 

RIGHT 

RIGHTS 

RND 

ROUNDING 

RSET 

SCALE 

SCRATCH 

SEG$ 

SELECT 

SEQUENTIAL 

SET 

SETUP 

SGN 

SI 

SIN 

SINGLE 

SIZE 

SLEEP 


t  Unreserved  keyword. 
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so 

SP 

SPACES 

SPAN 

SPEC% 

SQR 

SQRT 

STATUS 

STEP 

STOP 

STR$ 

STREAM 

STRING 

STRINGS 

SUB 

SUBEND 

SUBEXIT 

SUBSCRIPT 

SUMS 

SWAP% 

SYS 

TAB 

TAN 

TEMPORARY 

TERMINAL 

THEN 

TIM 

TIME 

TIMES 

TO 

TRMS 

TRN 

TYP 

TYPE 

TYPES 

UNALIGNED 

UNDEFINED 

UNLESS 

UNLOCK 

UNTIL 

UPDATE 

USAGES 

USEROPEN 

USING 

USRS 
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VAL 

VAL% 

VALUE 

VARIABLE 

VARIANT 

VFC 

VIRTUAL 

VPS% 

VT 

WAIT 

WHILE 

WINDOWSIZE 

WORD 

WRITE 

XLATE 

XLATE$ 

XOR 

ZER 


A.2  Reserved  Keywords  In  VAX  BASIC 

The  following  keywords  are  reserved  keywords  in  VAX  BASIC.  If  you  use 
these  keywords  in  a  program,  BASIC-PLUS-2  signals  the  warning  message 
"Keyword  <keyword>  is  reserved  in  VAX  BASIC."  It  is  recommended 
that  you  do  not  use  these  keywords  if  you  want  your  program  to  be 
transportable  to  VAX  BASIC. 

ACTIVATE 

ASK 

BASIC 

CAUSE 

CLEAR 

CONTINUE 

DEACTIVATE 

DEVICE 

DRAW 

GRAPH 

HANDLE 

HANDLER 

INFORMATIONAL 

INITIAL 

INKEY$ 

JSB 
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LBOUND 

NX 

NXEQ 

OF 

OPTIONAL 

PICTURE 

PLOT 

PROGRAM 

RETRY 

RMSSTATUS 

ROTATE 

SET 

SEVERE 

SHEAR 

SHIFT 

TRANSFORM 

UBOUND 

WARNING 

WHEN 
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Appendix  B 

Debugger  Commands 


This  section  describes  the  BASIC-PLUS-2  debugger  commands. 
BASIC-PLUS-2  debugger  commands  help  you  locate  run-time  errors 
and  debug  program  modules.  You  can  use  the  debugger  commands 
interactively  in  the  BASIC-PLUS-2  environment  or  from  DCL  command 
level.  To  use  debugger  commands,  you  must  compile  the  program  using 
the  /DEBUG  qualifier.  For  more  information  on  the  BASIC-PLUS-2 
debugger  see  the  BASIC-PLUS-I  User's  Guide. 
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BREAK 


BREAK 


The  BREAK  command  lets  you  stop  program  execution  at  a  specified  line 
number,  program  statement,  or  at  the  beginning  of  CALL  statements, 
user-defined  functions,  and  FOR,  UNTIL,  and  WHILE  loops.  The  program 
stops  before  executing  the  specified  breakpoint. 


Format 

BREAK 

f  ON  block  1 

{  [ON] stmnt-break.  ...  j  '  '  ‘ ' 

(  CALL  ] 

block: 

1  DEF 

1  LOOP  J 

stmnt-break:  lin-num[.stmnt-num  ]  [  ;iJiod-nam  ] 

Syntax  Rules 


1.  The  BREAK  command  with  no  parameters  sets  a  breakpoint  at  each 
line  number.  The  program  stops  at  each  line  number  before  executing 
any  statements  on  the  line. 

2.  Block  specifies  a  particular  statement  or  function  where  execution  is  to 
stop.  The  ON  keyword  must  precede  the  block.  You  can  specify  only 
one  block  in  each  BREAK  command. 

•  BREAK  ON  CALL  stops  execution  each  time  BASIC-PLUS-2  ex¬ 
ecutes  a  CALL  statement  to  a  subprogram.  The  program  stops 
before  any  statements  in  the  subprogram  execute.  If  you  are 
executing  a  task-built  program,  both  the  calling  and  the  called 
program  must  be  compiled  with  the  /DEBUG  qualifier;  otherwise, 
the  BREAK  ON  CALL  command  has  no  effect.  If  you  are  exe¬ 
cuting  a  program  in  the  BASIC -PLUS-2  environment,  the  called 
program  must  be  compiled  with  the  /DEBUG  qualifier. 
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BREAK 


•  BREAK  ON  DEF  stops  execution  each  time  BASIC-PLUS-2  en¬ 
counters  a  user-defined  function  in  a  module  compiled  with  the 
/DEBUG  qualifier.  The  statement  stops  before  any  statements  in 
the  function  execute. 

•  BREAK  ON  LOOP  stops  execution  each  time  BASIC-PLUS-2 
encounters  a  FOR,  WHILE,  or  UNTIL  statement  or  modifier. 

The  program  breaks  each  time  the  program  loops  back  to  the 
loop  statement.  The  program  stops  after  the  loop  is  initialized  or 
incremented,  but  before  any  statements  in  the  loop  execute. 

3.  Stmnt-break  specifies  a  particular  line  number  or  statement  where 
execution  is  to  stop.  You  can  specify  a  maximum  of  10  stmnt-break 
breakpoints.  If  you  specify  more  than  10  breakpoints,  BASIC-PLUS-2 
signals  the  error  message  "No  room." 

•  Lin-num  is  a  program  line  number. 

•  Stat-num  is  a  particular  statement  associated  with  the  specified 
line  number.  The  period  ( . )  is  required  and  must  immediately 
follow  the  line  number.  No  space  is  allowed  between  the  lin-num 
and  stat-num.  If  you  include  a  space  between  the  lin-num  and 
stat-num,  BASIC-PLUS-2  signals  an  error.  The  compiler  listing 
lists  statements  on  multi-statement  lines  by  line  and  statement 
number. 

•  Mod-nam  specifies  that  the  preceding  breakpoint  is  a  break¬ 
point  only  in  the  named  program  module.  The  semicolon  ( ; )  is 
required. 


Remarks 


1.  If  you  specify  a  stmnt-break  or  block  that  does  not  exist,  no  break 
occurs,  BASIC-PLUS-2  does  not  signal  an  error  or  warning,  and  the 
program  executes  normally. 

2.  To  disable  program  breakpoints,  use  the  UNBREAK  command. 
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BREAK 


Example 


#  BREAK  30.2,  6OO;PR0GB,  2OOO.3;PR0GC 

#  BREAK  ON  CALL 

#  CON 

BREAK  at  line  30  statement  2 

# 
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COMTINUE 


CONTINUE 

The  CONTINUE  command  continues  program  execution. 

Format 

CONTINUE 

Syntax  Rules 

None. 


Remarks 


When  you  have  finished  entering  debugger  commands,  type  the 
CONTINUE  command  to  resume  program  execution. 

Example 

«  BREAK  ON  LOOP 
«  CON 


Debugger  Commands  B-5 


CORE 


CORE 


The  CORE  command  returns  the  number  of  words  currently  allocated  in 
memory  for  your  entire  task.  Use  the  CORE  command  in  conjunction  with 
the  debugger  commands  FREE,  STRING,  and  I/O  BUFFER  to  determine 
how  memory  is  allocated  for  your  task. 


Format 

CORE 

Syntax  Rules 

None. 


Remarks 


1.  The  maximum  program  space  allowed  on  RSX  systems  is  32K  words 
minus  the  size  of  your  resident  library.  The  maximum  program 
space  allowed  on  RSTS/E  systems  is  31K  words  minus  the  size  of 
your  resident  library.  See  the  BASIC-PLUS-2  User's  Guide  for  more 
information  on  program  space  and  resident  libraries. 

2.  You  can  use  the  CORE  command  only  when  at  least  one  program 
module  has  been  compiled  with  the  /DEBUG  qualifier.  Note,  how¬ 
ever,  that  the  number  returned  by  the  CORE  command  reflects  the 
memory  allocation  for  the  entire  task,  not  just  the  program  module 
compiled  with  the  /DEBUG  qualifier. 

3.  Knowing  the  size  of  core  memory  can  help  you  control  the  size 
of  your  program  and  allow  you  optimize  to  accordingly.  See  the 
BASIC-PLUS-2  User's  Guide  for  more  information  on  optimization. 
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CORE 


Exampla 


«  CORE 
CORE  * 

# 


7647 
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ERL 


ERL 


The  ERL  command  returns  the  line  number  of  the  line  executing  when  the 
last  error  occurred. 


Format 

ERL 

Syntax  Rules 

None. 

Remarks 

If  no  error  has  occurred,  the  result  returned  by  the  ERL  command  is 
undefined. 

Example 


«  ERL 

ERL  *  1060 

# 
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ERN 


ERN 


The  ERN  command  returns  the  1-  to  6-character  name  of  the  program 
module  that  was  executing  when  the  last  successfully  handled  error 
occurred.  If  a  fatal  error  was  not  successfully  trapped,  control  passes  from 
the  debugger  to  command  level. 


Format 

ERN 

Syntax  Rules 

None. 

Remarks 


1.  The  ERN  command  returns  a  module  name  only  when  an  error  is 
handled  successfully. 

2.  If  no  error  occurs,  the  result  returned  by  the  ERN  command  is 
undefined. 


Example 


#  ERN 

ERN$  *  CHECKS 
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ERR 


ERR 


The  ERR  command  returns  the  error  number  of  the  last  error  that  oc¬ 
curred.  See  the  BASIC-PLUS-2  User's  Guide  for  a  list  of  errors  and  their 
numbers. 


Format 

ERR 

Syntax  Rules 

None. 


Remarks 

If  no  error  occurs,  the  result  returned  by  the  ERR  command  is  undefined. 


Example 


#  ERR 

ERR  =  65 

# 
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EXIT 


EXIT 

The  EXIT  command  returns  control  to  BASIC-PLUS-2  if  you  are  executing 
a  program  in  the  BASIC-PLUS-2  environment  and  to  command  level  if 
you  are  executing  a  task-built  program. 

Format 

EXIT 

Syntax  Rules 

None. 

Remarks 

The  EXIT  command  does  not  close  open  channels. 

Example 

#  EXIT 
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FREE 


FREE 

The  FREE  command  returns  the  number  of  words  currently  available 
in  memory  for  I/O  and  string  operations.  Use  the  FREE  command  in 
conjunction  with  the  debugger  commands  CORE,  STRING,  and  I/O 
BUFFER  to  determine  how  memory  is  allocated  for  your  task. 

Format 

FREE 

Syntax  Rules 

None. 

Remarks 

1.  When  string  or  I/O  operations  exceed  the  amount  of  available  free 
memory,  BASIC-PLUS-2  extends  the  amount  of  memory  allocated  for 
your  task. 

2.  Knowing  the  amount  of  free  memory  space  available  can  help  you 
control  the  size  of  your  program  and  optimize  accordingly.  See  the 
BASIC-PLUS-2  User's  Guide  for  information  on  optimization. 

Example 

«  FREE 

FREE  =  184 

» 
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I/O  BUFFER 


I/O  BUFFER 


The  I/O  BUFFER  command  returns  the  number  of  words  currently  allo¬ 
cated  for  I/O  buffer  space.  Use  the  I/O  BUFFER  command  in  conjunction 
with  the  debugger  commands  CORE,  STRING,  and  FREE  to  determine 
how  memory  is  allocated  for  your  task. 


Format 

I/O  BUFFER 

Syntax  Rules 

None. 


Remarks 


Knowing  the  size  of  the  I/O  buffer  can  help  you  control  the  size  of  your 
program  and  optimize  accordingly.  See  the  BASlC-PLUS-2  User's  Guide  for 
information  on  optimization. 


Example 


#  I/O  BUFFER 

I/O  BUFFERS  =  1765 

# 
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LET 


LET 


The  LET  command  allows  you  to  change  the  contents  of  program  vari¬ 
ables. 


Format 

LET  vbll  =  I  ] 
I  const  J 


Syntax  Rules 


1.  Vbll  specifies  a  numeric  or  string  variable  that  you  want  to  change. 

2.  Const  or  vbll  specifies  the  new  value  for  vbll.  You  can  specify  only  a 
constant  or  variable  name.  BASIC-PLUS-2  does  not  allow  expressions. 

3.  You  cannot  set  string  variables  to  a  null  string  with  the  LET  command. 
If  you  try  to  do  so,  BASIC-PLUS-2  signals  the  error  message  "Illegal 
syntax  in  LET."  However,  you  can  set  a  variable  to  the  null  string  in 
your  source  program  and  then  assign  that  variable  to  another  variable 
with  the  LET  command.  For  example: 

1000  NULL$= 

1010  A$=" HELLO" 

1020  PRINT  A$ 

Then,  compile  or  run  the  program  with  the  /DEBUG  qualifier,  estab¬ 
lish  a  breakpoint  at  line  1020,  and  set  A$  to  the  null  string  with  the 
LET  command.  For  example: 

BREAK  at  line  1020 
#  LET  A$  -  NULL! 
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LET 


Remarks 


1.  If  you  attempt  to  create  a  new  variable  with  the  LET  command, 
BASIC-PLUS-2  signals  the  error  "Illegal  syntax  in  LET." 

2.  Task-built  programs  must  be  compiled  with  the  /DEBUG  qualifier 
for  the  LET  command  to  take  effect.  BASIC-PLUS-2  signals  the  error 

Illegal  syntax  in  LET"  if  the  program  module  was  not  compiled  with 
the  /DEBUG  qualifier. 

3.  BASIC-PLUS-2  signals  the  error  "Illegal  syntax  in  LET"  when  you  try 
to  access  a  variable  across  modules  or  in  a  module  not  compiled  with 
the  /DEBUG  qualifier. 


Example 


*  LET  AX'ISX 

#  LET  NAME$-''EILEEN" 

» 
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PRINT 


PRINT 


The  PRINT  command  allows  you  to  display  the  current  contents  of 
program  variables. 


Format 

PRINT  vbl 


Syntax  Rules 

1.  Vbl  specifies  the  numeric  or  string  variable  whose  contents  you  want 
to  display. 

2.  Vbl  cannot  be  a  constant  or  expression. 


Remarks 


1.  When  executing  a  task-built  program,  you  can  access  only  those 
variables  contained  in  program  modules  that  have  been  compiled  with 
the  /DEBUG  qualifier. 

2.  Task-built  programs  must  be  compiled  with  the  /DEBUG  qualifier  for 
the  PRINT  command  to  take  effect. 

3.  BASIC-PLUS-2  signals  the  error  "Illegal  syntax  in  PRINT"  when  you 
try  to  access  a  variable  across  modules  or  in  a  module  not  compiled 
with  the  /DEBUG  qualifier. 


Example 


«  PRINT  C 

#  23 

# 
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RECOUNT 

The  RECOUNT  command  tells  you  how  many  characters,  including 
blanks  and  terminators,  were  transferred  by  the  last  I/O  operation. 


Format 

RECOUNT 


Syntax  Rules 

None. 


Remarks 

If  you  exit  from  your  program  without  closing  open  channels  or  executing 
the  END  statement,  the  Debugger  signals  the  error  "End-of-file  on  device." 
If  you  then  try  to  continue  program  execution  by  typing  the  CONTINUE 
command,  the  debugger  signals  the  error  "Can't  CONTINUE  or  STEP." 
When  you  exit  from  the  debugger,  files  are  not  closed  and  data  is  not 
transferred.  You  can  remedy  this  situation  by  including  an  error  handler 
which  passes  control  to  an  END  statement.  BASIC-PLUS-2  will  then  close 
files  and  transfer  data. 


Example 


#  RECOUNT 

RECOUNT  *  19 

# 
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REDIRECT 


REDIRECT 


The  REDIRECT  command  allows  you  to  direct  all  debugging  I/O  opera¬ 
tions  to  a  specified  terminal. 


Format 

REDIRECT  term-nam 


Syntax  Rules 

Term-nam  specifies  the  name  of  an  unattached  terminal.  The  terminal 
name  must  be  an  unquoted  string  that  corresponds  to  an  existing  terminal, 
or  BASIC-PLUS-2  signals  the  error  "Cannot  open  device." 


Remarks 


1.  The  program  executes  on  the  terminal  that  issued  the  RUN  command. 
Use  another  REDIRECT  command  to  direct  debugger  I/O  back  to  the 
terminal  on  which  the  program  is  executing. 

2.  You  can  use  the  REDIRECT  command  only  when  at  least  one  program 
module  has  been  compiled  with  the  /DEBUG  qualifier. 

3.  On  RSTS/E  systems,  if  the  specified  terminal  is  unavailable,  the 
debugger  signals  the  error  "Cannot  open  device."  On  RSX  systems, 
if  the  specified  terminal  is  unavailable,  the  debugger  stops  executing 
until  the  specified  terminal  is  available  and  does  not  signal  an  error. 


Example 


^  REDIRECT  KB2: 
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STATUS 


STATUS 


The  STATUS  command  returns  a  word-length  integer  that  contains 
information  about  the  last  opened  channel. 


Format 

STATUS 

Syntax  Rules 

None. 


Remarks 


1.  The  STATUS  function  returns  a  WORD  integer. 

2.  The  debugger  returns  the  last  STATUS  word. 

3.  On  RSTS/E  systems,  depending  on  the  error,  the  STATUS  function 

displays  a  value  representing  one  of  the  following: 

•  The  RMS- 11  primary  status  field  (STS)  or  the  RMS- 11  secondary 
status  field  (STV).  See  the  RSTS/E  RMS-11  MACRO  Programmer's 
Guide  for  more  information. 

•  The  device  characteristics  after  an  RMS- 11  OPEN  file  operation 
(set  by  the  DEV  field  of  the  FAB).  See  the  RSTS/E  RMS-11  MACRO 
Programmer's  Guide  system  for  more  information. 

•  For  OPEN  operations  where  no  error  occurs,  the  status  word 
describes  the  device  characteristics  of  the  FIRQB  and  FQFLAG 
field.  The  first  7  bits  describe  the  device,  and  bits  7  through  15 
describe  characteristics  of  the  OPEN  statement.  See  the 
BASIC-PLUS  Language  Manual  or  the  RSTS/E  System  Directives 
Manual  for  more  information  on  STATUS  values. 
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STATUS 


4.  On  RSX  systems,  depending  on  the  error,  the  STATUS  function 

displays  a  value  representing  one  of  the  following: 

•  The  RMS-11  primary  status  field  (STS)  or  the  RMS-11  secondary 
status  field  (STV).  See  the  RSX-llM/M-PLUS  RMS-ll  Macro 
Programmer's  Guide  for  more  information. 

•  The  device  characteristics  after  an  RMS-11  OPEN  file  operation 
(set  by  the  DEV  field  of  the  FAB).  See  the  RSX-llM/M-PlUS 
RMS-11  Macro  Programmer's  Guide  for  more  information. 

•  In  the  event  of  a  directive  error,  the  Directive  Status  Word  ($DSW) 
and  its  corresponding  error  code.  See  the  RSX-llM/M-PLUS  Mini 
Reference  for  the  error  codes. 

•  The  STATUS  field  of  a  QIO.  See  the  RSX-llM/M-PLUS  I/O 
Drivers  Reference  Manual  for  more  information. 

•  The  first  word  of  a  GETLUN  or  GLUN$  directive  describing 
device  characteristics.  See  the  RSX-llM/M-PLUS  and  Micro/RSX 
Executive  Reference  Manual  for  more  information. 

See  Table  4-7  for  a  list  of  the  values  of  the  STATUS  word  for 

OPEN  operations  where  no  errors  occur. 


Example 


#  STATUS 

STATUS  =  31 

# 
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STEP 


STEP 


The  STEP  command  causes  the  program  module  to  execute  statement  by 
statement,  stopping  after  a  specified  number  of  statements  have  executed. 


Format 

STEP  [  int-const  ] 


Syntax  Rules 


1.  Int-const  is  the  number  of  statements  to  be  executed  before  the 
program  stops.  It  must  be  a  positive  integer  from  1  through  32767. 

2.  You  must  include  a  space  between  the  STEP  command  and  int-const 
or  only  one  statement  executes. 

3.  STEP  with  no  int-const  is  the  same  as  specifying  STEP  1.  Only  one 
statement  executes  and  the  program  then  stops. 


Remarks 


1.  When  you  execute  a  task-built  program,  the  BASIC-PLUS-2  debugger 
only  counts  statements  executing  in  program  modules  compiled  with 
the  /DEBUG  qualifier. 

2.  If  a  module  not  compiled  with  the  /DEBUG  qualifier  executes  before 
a  module  compiled  with  the  /DEBUG  qualifier,  the  program  does  not 
stop  until  the  specified  number  of  statements  in  the  module  compiled 
with  /DEBUG  have  executed. 


Debugger  Commands  B-21 


STEP 


Example 


BREAK  at  line  .1050  statement  1 

#  STEP  2 

#  CON 

STEP  at  line  1050  statement  3 

» 
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STRING 


STRING 

The  STRING  command  tells  you  how  many  words  are  currently  allocated 
for  string  storage  for  your  entire  task.  Use  the  STRING  command  in 
conjunction  with  the  debugger  commands  CORE,  I/O  BUFFER,  and  FREE 
to  determine  how  memory  is  allocated  for  your  task. 

Format 

STRING 

Syntax  Rules 

None. 

Remarks 

Knowing  how  much  memory  is  allocated  to  string  operations  can  help 
you  control  the  size  of  your  program  and  optimize  accordingly.  See  the 
BASIC-PLUS-2  User's  Guide  for  information  on  optimization. 

Example 

«  STRING 

STRING  =  2086 

« 
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TRACE 


TRACE 


The  TRACE  command  displays  line  numbers  and  statement  numbers  as 
the  program  executes. 


Format 

TRACE 

Syntax  Rules 

None. 

Remarks 


1.  The  TRACE  command  does  not  affect  program  execution  or 
breakpoints. 

2.  A  task-built  program  must  be  compiled  with  the  /DEBUG  qualifier 
for  the  TRACE  command  to  take  effect.  When  the  BASlC-PLUS-2  en¬ 
counters  a  program  module  not  compiled  with  the  /DEBUG  qualifier, 
tracing  stops.  When  BASlC-PLUS-2  returns  to  a  module  compiled 
with  the  /DEBUG  qualifier,  tracing  resumes. 

3.  Specify  the  UNTRACE  command  to  disable  tracing.  See  the  descrip¬ 
tion  of  the  UNTRACE  command  for  more  information. 
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TRACE 


Example 


#  TRACE 

#  BREAK  300 

#  CONT 

at  line  100  statement  1 
at  line  100  statement  2 
at  line  200  statement  1 
BREAK  at  line  300  statement  1 
«  BREAK  500 

#  CONT 
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UNBREAK 


UniBREAK 


The  UNBREAK  command  disables  previously  set  breakpoints  in  programs 
and  subprograms. 


Format 

UNBREAK  I 


ON  block 
[ON]  stmnt-break, 


block: 


CALL 

DEF 

LOOP 


stmnt-break:  lin-num[.stmnt-num  ]  [  ;mod-nam  ] 


Syntax  Rules 


1.  ON  block  specifies  a  particular  statement  or  function  where  execution 
is  to  stop.  You  can  specify  only  one  ON  block  in  each  UNBREAK 
command: 

•  UNBREAK  ON  CALL  disables  breakpoints  that  occur  when 
BASIC-PLUS-2  executes  a  CALL  statement  to  a  subprogram. 

•  UNBREAK  ON  DEF  disables  breakpoints  that  occur  when 
BASIC -PLUS-2  encounters  a  user-defined  function  in  a  module 
compiled  with  the  /DEBUG  qualifier. 

•  UNBREAK  ON  LOOP  disables  breakpoints  that  occur  when 
BASIC-PLUS-2  encounters  a  FOR,  WHILE,  or  UNTIL  statement  or 
modifier. 

2.  Stmnt-break  specifies  a  particular  line  number  or  statement  where 
execution  is  to  stop. 

•  Lin-num  specifies  a  program  line  number. 
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UniBREAK 


•  Stat-num  specifies  a  particular  statement  associated  with  lin-num. 
The  period  ( . )  separator  is  required  and  must  immediately  follow 
the  line  number.  BASIC-PLUS-2  signals  an  error  if  you  include  a 
space  between  lin~num  and  stat-num.  The  cross-reference  section 
of  the  compiler  listing  lists  statements  on  multi-statement  lines  by 
number. 

•  Mod-nam  specifies  a  program  module  compiled  with  the  /DEBUG 
qualifier.  When  you  specify  a  module  name,  the  specified  line 
number  is  disabled  as  a  breakpoint  only  in  that  program  module. 
If  a  breakpoint  has  not  been  previously  set,  BASIC-PLUS-2  signals 
an  error. 

•  If  lin-num  or  stat-num  do  not  exist,  the  debugger  signals  the  error 
"Bad  line  spec  in  (UN)BREAK.'' 

3.  UNBREAK  with  no  parameters  disables  all  previously  specified 
stmnt-break  breakpoints.  ON  block  breakpoints  are  not  disabled. 


Remarks 


None. 


Example 


«  UNBREAK  ON  LOOP 


#  UNBREAK  100; GAMES.  500.  600.2 


#  CON 
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UNTRACE 


UniTRACE 


The  UNTRACE  command  disables  the  TRACE  command. 


Format 

UNTRACE 

Syntax  Rules 

None. 


Remarks 

Enter  the  UNTRACE  command  when  the  program  encounters  a  specified 
breakpoint  and  stops  executing. 


Example 


#  UNTRACE 

#  CON 
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Appendix  C 

Editing  Mode  Commands 


This  appendix  describes  the  BASIC-PLUS-2  editing  mode  commands.  To 
use  the  editing  mode  commands,  type  the  EDIT  command  while  in  the 
BASIC-PLUS-2  environment.  Once  you  type  the  EDIT  command, 
BASIC-PLUS-2  places  you  in  editing  mode  where  you  can  use  the  editing 
mode  commands  to  modify  your  program.  See  Chapter  2  for  more 
information  on  the  BASIC-PLUS-2  EDIT  command. 
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DEFINE 


DEFINE 


The  DEFINE  editing  mode  command  allows  you  to  enter  a  macro  defini¬ 
tion.  A  macro  definition  consists  of  a  series  of  editing  mode  commands  in 
the  order  in  which  they  are  to  execute. 


Format 

DEFINE 


Syntax  Rules 

The  DEFINE  and  EXECUTE  editing  mode  commands  are  invalid  in  a 
macro  definition.  If  you  specify  these  commands  in  your  macro  definition, 
BASIC-PLUS-2  signals  an  error  message. 


Remarks 


1.  To  create  a  macro  definition,  type  the  DEFINE  command. 
BASIC-PLUS-2  displays  the  DEFINE  prompt  (->  ).  Next,  type  the 
editing  mode  commands  in  the  sequence  in  which  you  want  them  to 
execute.  When  you  are  finished,  type  EXIT  or  CTRL/Z  to  exit.  You 
can  then  use  the  EXECUTE  command  to  execute  your  macro  defini¬ 
tion.  See  the  description  of  the  EXECUTE  editing  mode  command  for 
more  information. 

2.  BASIC-PLUS-2  writes  the  macro  definition  to  a  file,  so  the  definition 
remains  in  effect  until  you  enter  another  DEFINE  command. 
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DEFINE 


Example 


*  DEFINE 

Enter  command  sequence: 
">FIND  REM 
->SUBSTITUTE  /REM/!/ 
->EXIT 

*  EXECUTE 
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EXECUTE 


EXECUTE 

The  EXECUTE  editing  mode  command  executes  the  last  macro  defined  by 
the  DEFINE  command.  You  specify  the  number  of  times  the  macro  is  to 
execute. 

Format 

EXECUTE 

[int-const] 

Syntax  Rules 

Int-const  specifies  the  number  of  times  the  macro  executes.  If  you  do  not 
specify  int-const,  BASIC-PLUS-2  executes  the  macro  once. 

Remarks 

An  EXECUTE  command  always  executes  the  last  defined  macro  definition. 
If  no  macro  definition  exists,  BASIC-PLUS-2  signals  the  error  "Command 
sequence  has  not  been  defined." 

Example 

*  EXECUTE  5 
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EXIT 


EXIT 


The  EXIT  or  CTRL/Z  editing  mode  command  marks  the  end  of  a  DEFINE 
or  INSERT  command  or  exits  you  from  editing  mode. 


Format 

EXIT 

Syntax  Rules 

None. 


Remarks 


^TRL/Z  in  response  to  the  editing  mode  prompt, 
BASIC-PLUS-2  exits  from  the  editing  mode. 

2.  If  you  type  EXIT  or  CTRL/Z  to  end  a  DEFINE  or  INSERT  command, 
BASIC-PLUS-2  displays  the  editing  mode  prompt  and  you  can  enter 
more  editing  mode  commands. 


Example 


*  DEFINE 

Enter  command  sequence 
->FIND  REM 
->SUBS  /REM/! 

’>EXIT 


♦ 
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FIND 


FIND 


The  FIND  editing  mode  command  searches  the  curreiit  program  for  a 
specified  string  starting  at  the  last  edited  line  and  continuing  to  the  end  of 
the  program. 


Format 

FIND  [unq-str] 


Syntax  Rules 


1.  Unq-str  specifies  the  string  you  want  to  find. 

2  If  you  do  not  specify  a  unq-str,  the  FIND  command  matches  the  unq- 
str  specified  by  the  last  FIND  command.  If  there  is  no  previous  FIND 
command,  BASIC-PLUS-2  matches  the  first  character  of  the  last  edited 
line. 


Remarks 


1.  When  BASIC-PLUS-2  locates  the  string,  BASIC -PLUS-2  displays  the 
line  containing  the  string  and  sets  it  as  the  last  edited  line. 
BASIC-PLUS-2  also  displays  an  informational  message. 

2.  If  the  string  does  not  exist,  the  last  edited  line  remains  unchanged  and 
BASIC-PLUS-2  displays  a  message  which  informs  you  that  the  string 
was  not  located. 

3  The  FIND  command  matches  the  string  exactly  as  you  type  it.  If  the 
string  is  uppercase,  BASIC-PLUS-2  searches  for  matching  uppercase 
characters. 
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FIND 


Example 


*  FIND  PRIMT 

330  PRIMT  'How  many  receipts  do  you  have *; RECEIPTS 
"PRIMT"  found  on  line  330 
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INSERT 


The  INSERT  editing  mode  command  allows  you  to  add  lines  to  a  program. 


Format 

INSERT  [lin-num] 


Syntax  Rules 

1.  Lin-num  specifies  the  line  number  after  which  you  want  to  insert  new 
program  lines. 

2.  If  the  line  number  does  not  exist,  BASIC-PLUS-2  signals  an  error. 

3.  If  you  do  not  specify  a  line  number,  BASIC-PLUS-2  inserts  program 
lines  after  the  last  edited  line. 

4.  The  first  line  of  the  inserted  lines  must  begin  with  a  line  number. 


Remarks 


1.  To  insert  program  lines,  enter  the  INSERT  command  and  then  type  in 
the  program  lines  you  want  to  insert.  When  you  are  finished  inserting 
lines,  type  the  EXIT  command  to  return  to  editing  mode. 
BASIC-PLUS-2  displays  the  editing  mode  prompt  and  you  can  enter 
more  editing  subcommands. 

2.  If  you  insert  a  line  number  that  already  exists,  BASIC-PLUS-2  replaces 
the  existing  line  with  the  code  you  insert  and  does  not  signal  a 
warning. 

3.  BASIC-PLUS-2  does  not  perform  syntax  checking  on  program  lines 
inserted  by  the  INSERT  command. 

4.  The  current  edit  line  does  not  change.  For  example,  if  the  current  edit 
line  is  10  and  you  insert  lines  20  and  30,  line  10  remains  the  current 
edit  line. 
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INSERT 


Exaiaple 


*  INSERT  30 

Enter  lines  to  be  added  after  line  30 
■>40  INPUT  'More  receipts' ;RECEIPTS| 
■>60  IF  RECEIPTS!  ■  "" 

THEN  GOTO  32767 
■>  END  IF 

“>  EXIT 
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SUBSTITUTE 


SUBSTITUTE 

The  SUBSTITUTE  editing  mode  command  allows  you  to  substitute 
one  character  string  for  another  in  the  program  currently  in  memory. 
SUBSTITUTE  is  the  editing  mode  equivalent  of  the  EDIT  command  with 
one  exception:  you  cannot  specify  a  range  of  lines.  The  SUBSTITUTE 
subcommand  can  replace  only  one  occurrence  of  the  specified  search 
string,  while  the  EDIT  command  can  replace  all  occurrences  in  a  range  of 
lines,  if  you  so  specify. 


Format 

SUBSTITUTE  search-clause  [  replace-clause  ] 
search-clause:  delim  unq-strl  delim 

replace-clause:  [  unq-str2  ]  [  delim  ]  [  int-const  ] 


Syntax  Rules 

1.  Delim  is  a  unique  delimiter  character  that  marks  the  beginning  and 
end  of  the  search  and  replace  strings. 

•  Delim  cannot  be  a  character  used  in  the  search  or  replace  strings. 

•  The  beginning  and  ending  delim  characters  must  match,  or 
BASIC-PLUS-2  signals  an  error. 

2.  Unq-strl  specifies  the  string  you  want  to  remove  or  replace.  Unq-strl 
specifies  the  string  to  be  substituted  for  unq-strl. 

•  If  unq-strl  is  found,  BASIC-PLUS-2  replaces  it  with  unq-strl. 

•  If  unq-strl  is  not  found,  BASIC-PLUS-2  signals  an  error. 

•  If  you  do  not  specify  unq-strl,  BASIC -PLUS-2  deletes  unq-strl. 

•  If  you  do  not  specify  unq-strl,  BASIC-PLUS-2  replaces  the  first 
character  of  the  last  edited  line  with  unq-strl. 
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SUBSTITUTE 


•  The  SUBSTITUTE  command  matches  and  replaces  strings  ex¬ 
actly  as  you  type  them.  If  unq-strl  is  uppercase,  BASIC-PLUS-2 
searches  for  an  uppercase  string.  If  it  is  lowercase,  BASIC-PLUS-2 
searches  for  a  lowercase  string. 

3.  Int-const  specifies  the  occurrence  of  str-litl  you  want  to  replace.  If 
you  do  not  specify  an  int-const,  BASIC-PLUS-2  replaces  the  first 
occurrence  of  str-litl. 

4.  If  you  specify  the  SUBSTITUTE  command  without  an  argument, 
BASIC-PLUS-2  signals  the  error  "Parameters  required." 


Remarks 


BASIC-PLUS-2  displays  the  edited  line  with  changes  after  the 
SUBSTITUTE  command  executes. 


Example 


♦  SUBSTITUTE  /AX/ABSOLUTEX/3 
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Appendix  D 

Object  Time  System  Routines 


This  appendix  contains  a  list  of  the  module  names  in  the 

BASlC-PLUS-2  Object  Time  System  (OTS)  and  a  brief  description  of  each 
of  their  functions. 


Table  D-1; 

Module 

Name 

$BTDID 

$BTDLD 

$CALLR 

$CALLS 

$CHANG 

$CNTRL 

$ERTHR 

$FUNC1 

$FUNC2 

$FUNC3 

$FUNC4 

$LOADS 

$MATIC 

$MAT1D 

$MATIF 


Control,  Matrix,  and  Miscellaneous  Modules 

Description 

Logical  functions 

Logical  functions— LONGWORD 
CALL  thread — BY  REF 
CALL  thread — BP2 
ASCII  string  conversions 
GOTO  and  branch  statements 
Error  threads 

Function  call  threads  (obsolete) 

General  function  threads 
DEF*  function  code  thread 
DEF  function  code  thread 
Loading  of  truth  values 
Matrix  inversion— COMMON 
Matrix  inversion — DOUBLE 
Matrix  inversion— FLOATING 
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Table  D- 

1  (Cent.):  Control,  Matrix,  and  Miscellaneous 
Modules 

Module 

Name 

Description 

$MTRET 

Matrix  inversion — RELOAD  RETURN 

$MATRT 

Matrix  inversion — root 

$MATRX 

Matrix  threads 

$NEGAT 

Negate  operations 

$REDIM 

General  redimensioning  routine 

$TESTS 

Logical  test  routines 

$RUNDN 

Dummy  routine  to  fill  $ICIOO 

Table  D- 

-2:  String  Moduies 

Module 

Name 

Description 

$PROCT 

CTRL/C  protection  routine 

$SSCST 

Subscript  routines  for  common  string  arrays 

$SSOFF 

Find  offset  into  array 

$SSPTR 

Subscript  pointer  mode  threads 

$SSRDM 

Redimensioning  thread 

$SSSUB 

Subscript  routines  for  normal  arrays 

$SSVIR 

Subscripting  for  virtual  arrays 

$STCFS 

String/numeric  conversion  functions 

$STCMP 

String  comparison  routines 

$STCOS 

String  concatenation  routines 

$STCVT 

String  conversion  function 

$STFNS 

String  functions 

$STFN1 

String  functions  (continued) 

$STGTA 

String  get  a  mode  source  routines 

$STLSS 

String  left  set  routines 

$STMOS 

String  move  routines 
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Table  D-2  (Cont.);  String  Modules 


Module 

Name 

Description 

$STMSC 

$STNMD 

$STNMF 

$STNML 

$STRSS 

$STVLD 

$STVLF 

$STVLI 

$STVLL 

$STXCM 

$STXLT 

$SWPST 

String  routines  (miscellaneous) 

DOUBLE  NUM(1)$  function 

SINGLE  NUM(1)$  function 

LONGWORD  NUM(1)$  function 

String  right  set  routines 

VAL  function — DOUBLE 

VAL  function 

VAL  function 

VAL  function — LONGWORD 

XLT-CVT  common  routines 

String  XLATE  function 

Swap  stack  locations 

Table  D-3: 

Common  Math  Modules 

Module 

Name 

Description 

$BMOVS 

$BNEXT 

$DCMP 

$DMOV 

$DRAND 

$DTAN 

$DTIME 

$DXDD 

$ECDF 

$ECONV 

$ECPY 

$EMISC 

BYTE  moves 

BYTE  next  threads 

DOUBLE  comparison  routines 

DOUBLE  moves 

RND  DOUBLE 

DOUBLE  tangent 

TIME(X%)  function — DOUBLE 

DOUBLE  DOUBLE 

Approximate  FLOATING/DOUBLE  comparison 

FLOATING  formatted  conversion 

DOUBLE/SINGLE  copy  threads 

ABSOLUTE  VALUE/SIGN  FUNCTIONS 
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Table  D-3  (Cent.):  Common  Math  Modules 


Module 

Name 

Description 

$FCMP 

$FMOV 

$FRAND 

$FTAN 

$FXFF 

$JADDS 

$]CMPS 

$JCOMP 

$JCONV 

$JDIVS 

$JMISC 

$JMOVS 

$JMUL 

$JNCR 

$JNEXT 

$JPADD 

$JPCMP 

$JPMOV 

$JPSUB 

$JSUBS 

$JXII 

$LADDS 

$LCMP 

$LCOMP 

$LCON2 

$LCONV 

$LDIV 

$LXLL 

FLOATING  comparisons 

FLOATING  moves 

RND/RANDOMIZE 

Tangent  FLOATING 

SINGLE  **  SINGLE 

INTEGER  addition 

INTEGER  comparison 

INTEGER  complements 

INTEGER  conversion  routines 

INTEGER  division 

ABS  function 

Simple  INTEGER  moves 

INTEGER  multiplication 

Increments  and  decrements 

INTEGER  next  threads 

INTEGER  addition  with  arguments 

INTEGER  argument  comparison 

INTEGER  argument  movement 

INTEGER  subtraction  with  arguments 

INTEGER  subtraction 

INTEGER  **  INTEGER 

LONGWORD  addition 

LONGWORD  comparison 

LONGWORD  complement 

LONGWORD  and  INTEGER  conversion 

LONG  INTEGER  conversion  routines 

LONGWORD  division 

LONGWORD  exponentiation  routine 
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Table  D— 3  (Cont.):  Cotiinfion  Math  Modules 


Module 

Name 

Description 

$LMISC 

$LMUL 

$LNEXT 

$LSUBS 

$RCMP 

$RMOV 

ABS— LONGWORD 

LONGWORD  multiplication 

LONGWORD  next  threads 

LONGWORD  subtraction 

RFA  comparison 

RFA  movement 

Table  D-4: 

FPU  Math  Modules 

Module 

Name 

Description 

$BFPER 

$BFPEI 

$DATAN 

$DCONl 

$DDIV 

$DEXP 

$DFIX 

$DINT 

$DLOG 

$DMUL 

$DSCAL 

$DSIN 

$DSQRT 

$DXDI 

$FADD 

$FADDA 

$FADDM 

$FADDP 

Floating-point  setup 

Floating-point  error 

Double-precision  arctangent 

DOUBLE-to-INTEGER  conversion 

Double-floating  divide 

Double-precision  EXP 

DOUBLE-to-DOUBLE  truncation 

INTEGER  part  of  DOUBLE 

Double-precision  LOG 

Double-floating  multiplication 

SCALE  factor  preprocessor 

Double-precision  SIN  and  COS 

Double-precision  square  root 

DOUBLE  **  INTEGER 

Floating  addition 

Real  addition  through  address 

Real  addition  to  memory 

Real  addition  to  pointer 
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Table  D-4  (Cent.):  FPU  Math  Modules 


Module 

Name 

Description 

$FATAN 

Arctangent 

$FCONl 

FLOAT-to-INTEGER  conversion 

$FDIV 

$FEXP 

Floating  division 

Real  exponent  routine 

$FFIX 

$FINT 

Real-to-real  truncation 

INTEGER  part  of  real 

$FLOG 

Single-precision  log 

$FMUL 

FLOATING  multiplication 

$FNEXT 

$FSIN 

$FSQRT 

$FXFI 

FLOATING  next  threads 

FLOATING  SIN 

FLOAT  square  root 

FLOATING  *•  INTEGER 

$JCONl 

$LCONl 

$MATII 

INTEGER  to  FLOAT  conversion 

LONGWORD  conversion 

Matrix  inversion — INTEGER 

Table  D-5: 

Common  I/O  Modules 

Module 

Name 

Description 

$ICCRL 

$ICEOL 

Shared  RMS  OPEN  code 

End  I/O  list 

$ICEND 

$ICFLD 

$ICINI 

$ICIOO 

$ICMOV 

SICPRG 

$ICRCL 

Common  end 

Field  threads 

I/O  initializations 

AST  vector  area 

Buffer  move  threads 

PRINT  USING  (all  types) 

Common  close  thread 
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Table  D-5  (Cont.);  Common  I/O  Modules 


Module 

Name 

Description 

$ICRDD 

Input  DOUBLE 

$ICRDL 

DELETE  threads 

$ICRED 

Common  inputs  (all  types) 

$ICRE1 

New  READ  routines 

$ICRFG 

FIND/GET  threads 

$ICRKY 

FIND/GET  key  thread 

$ICRMP 

REMAP  move  threads 

$ICRPT 

PUT  threads 

$ICRSC 

SCRATCH  thread 

$ICRSR 

RESTORE  thread 

$ICRUL 

UNLOCK  thread 

SICRUN 

UPDATE  thread 

$ICULT 

Common  utility  routines 

$ICUL1 

Common  utility  routines 

$ICWRT 

PRINT  (all  variables) 

$ICWR1 

PRINT  LONGWORD  variables 

$IVVIR 

Virtual  block 

RAD50 

ASCII  string  to  RAD50  conversion 

RQLCB 

Core  block  request  and  release 

SAVRG 

Non-volatile  registers  save  or  restore 

$OVSGl 

Overlay  SEG  1  routine 

$OVSG2 

Overlay  SEG  2  routine 

$OVSG3 

Overlay  SEG  3  routine 

$OVSG4 

Overlay  SEG  4  routine 
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Table  D-6:  RMS  I/O  Modules 


Module 

Name 

Description 

$ICFSP 

Return  file  information 

* 

$1MALL 

Common  code  for  all  RMS 

$IMALQ 

RMS  allocation  routines 

$IMCLS 

Common  CLOSE — RMS 

$IMDEL 

Common  DELETE 

$1MFGC 

Common  for  FIND/GET 

$IMGSA 

RMS  allocation  routines 

$IMOPN 

Shared  RMS  OPEN  code 

$IMPUT 

Common  PUT 

$IMRES 

Common  RMS  RESTORE 

$IMUPD 

Common  UPDATE 

$IROPN 

Relative  OPEN 

$IRROT 

Relative  root  resident  module 

$ISROT 

Sequential  root  resident  module 

$ISSCR 

Sequential  SCRATCH 

$IUROT 

Undefined  root  resident  module 

$1XCLS 

Indexed  CLOSE 

$IXOPN 

Indexed  OPEN 

$IXROT 

IDX  root  resident  module 

$RMSUP 

AST  vector  area 

$CMRMS 

AST  vector  area 

Table  D-7:  RSTS/E-  Specific  Modules 


Module 

Name 

Description 

$BERFS 

File  names  for  error 

$BINIT 

Run-time  initializations 

$BXTRA 

Extra  routines 
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Table  D- 

Module 
Name 

$CCTRP 

$DEBUG 

$ERROR 

$ERROT 

$FTIME 

$ICFNS 

$ICFSS 

$ICI02 

$ICROP 

$ICTRM 

$IECHN 

$IEMSC 

$IESPX 

$IESYS 

$IEULT 

SIMATR 

$IMERR 

$IMROT 

$IMULK 

$ISCLS 

SISOPN 

$IVOPN 

PATCH 

$START 

$STPDB 

$TIME 

$CMROT 

$RNROT 


Description 

BASIC-PLUS-2  CTRL/C  trap 
BASIC-PLUS-2  Debugger 
Error  handler 
Error  handler 
TIME(X%)  function 
Non-FIP  CALL  functions 
File  string  scan 

I/O  impure  area  (such  as  FAB) 
Common  OPEN  thread 
System  terminal  functions 
CHAIN  thread 
I/O  functions 
SPEC  function 
basic-plus-2  SYS  function 
I/O  utilities 
Read  file  attributes 
RMS  error  handler 
RMS  root  resident  code 
RMS  UNLOCK  (free  and  release) 
Sequential  CLOSE— RMS 
Sequential  OPEN 
Virtual  OPEN 
Patch  space 

String  arithmetic  functions 
Stop  processor  for  debugger 
TIME  function 

Compiler  root  resident  module 
RUN  controller 
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Table  D-8: 

Module 
Name 
$BERFS 
$BINIT 
$CCTRP 
$DEBUG 
$ERROR 
$ERROT 
$FTIME 
$ICFNS 
$ICFSS 
$ICI02 
$ICROP 
$ICTRM 
$IMATR 
$IMERR 
$IMROT 
$IMULK 
$IQCHN 
$IQKIL 
$IQMGT 
$IQMSC 
$IQNMA 
$IQROT 
$IQULT 
$ISCLS 
$ISOPN 
$IVOPN 
PATCH 
$START 


Description 
File  names  for  error 
Run-time  initializations 
BASlC-PLUS-2  CTRL/C  trap 
Debugger  for  BASlC-PLUS-2 
Error  handler 
Error  handler 
T1ME(X%)  function 
Non-FlP  CALL  functions 
File  string  scan 

I/O  impure  area  (such  as  FAB) 
Common  OPEN  thread 
System  terminal  functions 
Read  file  attributes 
RMS  error  handler 
RMS  root  resident  code 
RMS  unlock  (free  and  release) 
CHAIN  thread 
KILL  function 
MAGTAPE  functions 
I/O  functions 
NAME.. .AS  function 
Terminal  I/O  root 
I/O  utilities 

SEQUENTIAL  close  -  RMS 
SEQUENTIAL  open 
VIRTUAL  open 
Patch  space 

STRING  arithmetic  functions 
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Tabla  D  8  (Cont.);  RSX-Specific  Modulos 


Module 

Name 

Description 

$STPDB 

Stop  processor  for  debug 

$TIME 

TIME  function 

$IVROT 

Virtual  root  resident  module 

$CMROT 

Compiler  root  resident  module 

IRNROT 

Run  controller 
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INDEX 


A 


%  ABORT  directive  •  3-2 
ABS%  function  •  4-4 
ABS  function  •  4-2 
Absolute  value 

ABS%  function  •  4-4 
ABS  function  •  4-2 
MAG  function  *4-151 
ACCESS  clause  *4-2 14,  4-246 
ALLOW  clause  •  4-2 1 4 
Alphanumeric  label*  1-2 
See  also  Labels 

ALTERNATE  KEY  clause  *4-220 
Ampersand  (&) 

as  a  continuation  character*  1-5,  1-7,  1-12 
in  DATA  statement  *  4-38 
APPEND  command  *  2-3  to  2-5 
Arc  tangent  *  4-6 
Arithmetic  operators*  1-37,  1-38 
Array*  1-21 

array  elements*  1-21 

assigning  values  to  *4- 164,  4-166,  4-174, 
4-256 

bounds  *4-20,  4-42,  4-63,  4-65,  4-163, 
4-166,  4-168,  4-172,  4-174 
converting  with  CHANGE  statement  *4- 19 
creating  *  4-62 

creating  with  COMMON  statement  *  4-26 
creating  with  DECLARE  statement  *  4-42 
creating  with  MAP  statement  *4- 156 
creating  with  MAT  statement  *4- 162,  4-166, 
4-168,  4-171,  4-174 
data  type  *  4-62 


Array  (cont'd.) 

definition  of*  1-22 
dimensioning  *4-65,  4-163 
dimensions*  1-22,  4-62 
dynamic  *4-62,  4-63,  4-65 
elements  of  *  4-63 

element  zero*  1-22,  4-64,  4-163,  4-167, 
4-169,  4-172,  4-175,  4-186 
errors  In  *  4-63 
initialization  of  *4- 164 
initializing  *4-65 
Inversion  of  *4-165 
naming*  1-21,  1-23 
redimensioning  *4-174 
redimensioning  with  MAT  statement  *4-163, 
4-167,  4-169 
size  limit*  1-22 
static  *  4-62,  4-63 
subscripts  *  4-63 
transposing  *4- 165 
virtual*  1-23,  4-44,  4-62,  4-64 
ASCII 

characters*  1-35,  1-42,  4-22 
character  set*  1-12 
conversion  *4- 19,  4-22 
converting  to  *  4-5 
function  *  4-5 
radix*  1-32 
Asterisk  (*) 

in  PRINT  USING  statement  *  4-238 
with  HELP  command  *  2-32 
ATN  function  *  4-6 


Index- 1 


B 


Backslash  (\) 

in  continued  lines*  1-7 
in  multi-statement  lines*  1-6 
in  PRINT  USING  statement  *  4-240 
statement  separator*  1-6 
BASIC-PLUS-2  character  set*  1-12 
Binary  radix*  1-32 
Blank-if-zero  field 

In  PRINT  USING  statement  *  4-238 
Block 

CASE  *4-283 
SELECT  *4-283 
Block  I/O  file 

finding  records  In  *4-91 
opening  *4-2 18 

retrieving  records  sequentially  In  *4-1 12 
writing  records  to  *  4-246 
BLOCKSIZE  clause  *4-2 15 
Block  statement 
ending  *  4-7 1 
exiting  *  4-79 
Bounds 

default  for  implicit  arrays  *4-64,  4-163,  4-166, 
4-168,  4-172,  4-174 
definition  of  *  1  -2 1 
maximum*  1-21 

upper  bounds  with  DECLARE  statement  *  4-43 
BREAK  debugger  command  *B-1,  B-4 
Breakpoint 

disabling*  B-25 
setting* B-1,  B-2 
BRLRES  command  *  2-6 
Bucket 

creating  with  BUCKETSIZE  clause  *4-2 15 
locking  *4-1 12 
unlocking  *4-1 12 
BUCKETSIZE  clause  *4-2 15 
BUFFER  clause  *4-2 15 
BUFSIZ  function  *  4-7 
BUILD  command  *  2-9 
/BYTE  qualfier*2-11 
/DSKLIB  qualifier  *2- 11 
/EXTEND  qualifier  *2- 12 
/LIBRARY  qualifier  *2- 12 
/[NOJCLUSTER  qualfier*2-1 1 


BUILD  command  (cont'd.) 

/[NOpUMP  qualifier* 2-11 
/[NO]IDS  qualifier  *2- 12 
/[NOJINDEX  qualifier  *2- 12 
/[NO]MAP  qualifier  *2- 13 
/[NO]RELATIVE  qualifier* 2-13 
/[NOISEQUENTIAL  qualifier*  2-14 
/[NO] VIRTUAL  qualifier  *2- 14 
/ODLRMS  qualifier  *2- 13 
/RMSRES  qualifier  *2- 13 
BYTE  data  type*  1-13 


c 


CALL  statement  *  4-8  to  4- 1 3 
Caret  ( " ) 

In  PRINT  USING  statement* 4-237 
CASE  clause  *4-284 
CASE  ELSE  clause  *4-284 
CAUSE  ERROR  statement  *4- 14 
CCPOS  function  *4-15 
CD  formatting  character 

in  PRINT  USING  statement  *  4-237 
Centered  field 

in  PRINT  USING  statement  *  4-240 
C  formatting  character 

in  PRINT  USING  statement  *  4-240 
CHAIN  statement  *4- 17  to  4-18 
CHANGES  clause  *4-221 
CHANGE  statement  *4- 19  to  4-21 
Character 

ASCII*  1-35,  1-42,  4-5,  4-22 
data  type  suffix  *  1  - 1 6 
formatting  with  PRINT  USING  statement* 
4-237  to  4-241 
lowercase  *  2-27,  4-240 
nonprinting*  1-34 
position 

CCPOS  function  *4-15 
of  substring  *4- 129 
processing*  1-12 
uppercase  *  2-27,  4-240 
wildcard  *  2-32 
CHARACTER  data  type*  1-34 
Character  position 
of  substring  *  4-230 


2-Index 


Character  set 
ASCII*  1-12 
BASIC-PLUS-2*  1-12 
translating  with  XLATE$  function  *  4-332 
CHR$  function  *  4-22 
Clauses 

ACCESS  *4-2 14,  4-246 
ALLOW  *4-2 14 
ALTERNATE  KEY  *4-220 
BLOCKSIZE*4-215 
BUCKETSIZE*4-215 
BUFFER  *4-2 15 
BY  *4-9,  4-84,  4-303 
CASE  *4-284 
CASE  ELSE  *4-284 
CHANGES  *4-221 
CLUSTERSIZE*4-215 
CONNECT  *4-2 16 
CONTIGUOUS  *4-2 16 
COUNT  *4-245,  4-325 
DEFAULTN  AME  *4-213,4-216 
DUPLICATES  *4-221,  4-247 
ELSE  *4-1 19 
END  IF*4-119 
EXTENDSIZE*4-217 
FILESIZE*4-217 
FOR  *4-2 13 

KEY  *4-89,  4-110,  4-270 
MAP  *4- 158,  4-217 
MODE  *4-2 18 
[NO]SPAN*4-218 
NOREWIND  *4-2 18 
ORGANIZATION  *4-2 18 
OTHERWISE  *4-205,  4-207 
PRIMARY  KEY  *4-220 
RECORD  *4-89,  4-110,  4-245,  4-246 
RECORDSIZE*4-158,  4-221,  4-245 
RECORDTYPE*  4-221 
RFA*4-89,  4-110 
STEP  *4-97 
TEMPORARY  *4-222 
UNTIL  *4-98 
USEROPEN*  4-222 
WHILE  *4-98 
WINDOWSIZE*  4-222 
CLOSE  statement  *  4-23 
CLUSTERSIZE  clause  *4-2 15 


Colon  (:) 

in  labels*  1-2 
Comma  (,) 

in  DATA  statement  *  4-39 
in  DELETE  command  *  2-22 
in  EXTRACT  command  *  2-30 
in  INPUT  LINE  statement  *4- 126 
in  INPUT  statement  *4- 122 
in  LINPUT  statement  *4- 142 
in  LIST  command  *  2-38 
in  MAT  PRINT  statement  *  4- 1 7 1 
In  PRINT  statement  *  4-232 
in  PRINT  USING  statement  *4-237 
Command  file 
generating  *  2-9 
Comment 
field  *1-9 

in  DATA  statement*  1-10,  4-38 
In  REM  statement  *  4-262 
processing*  1-12 
REM  statement*  1-11 
terminating*  1-10 
transferring  control  to  *  1  -9 
Common 
area  *  4-28 
COMMON  area 
size  of  *  4-28 

COMMON  statement  *  4-25  to  4-29 
FILL  keywords  *  4-26 
with  FIELD  statement  *4-87 
COMP%  function  *  4-30 
Compilation 

conditional  *3-6,  3-22 

controlling  with  OPTION  statement  *  4-225 

control  of*  1-8,  2-70 

control  of  listing  *3-3,  3-12,  3-13,  3-14,  3-15, 
3-16,  3-18,  3-20 
including  source  code*  1-8 
listing  *2- 15 

line  numbers  In*  1-7 

terminating  with  %  ABORT  directive  *  3-2 
COMPILE  command  *2- 15  to  2-21 
/BYTE  qualfler  *2-17 
/DOUBLE  qualifier*  1-17,  2-18 
/LONG  qualifier  *2-19 
/[NO]CHAIN  qualfier*2-17 
/[NO]CROSS_REFERENCE  qualifier  *2-17 
/[NO]DEBUG  qualfler  *2- 17 
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COMPILE  command  (cont'd.) 

/[NOJFLAG  qualifier  •2- 18 
/[NO]LINE  qualifier  •2- 18,  4-74 
/[NO]LIST  qualifier  *2- 18 
/[NO]MACRO  qualifier  *2- 19 
/[NojoBJECT  qualifier  *2- 19 
/[NO]SCALE  qualifier  •2- 19 
/[NO]SYNT  AX -CHECK  qualifier*  2-20 
/[NO]W ARMINGS  qualifier  •  2-20 
/PAGE-SIZE  qualifier  *2- 19 
/SINGLE  qualifier  *2-20 
/TYPE-DEFAULT  qualifier*  1-16,  2-20 
/VARIANT  qualifier  *2-20,  3-22 
/WIDTH  qualifier  *2-21 
/WORD  qualifier  *2-21 
Compiler  commands 

See  Environment  commands 
Compiler  directives*  1-8,  3-1  to  3-23 
%ABORT*3-1 
%CROSS*3-3 
%IDENT*3-4 

%IF-%THEN-%ELSE-%END  %IF*3-6 
%INCLUDE*3-8 
%LET*3-10 
%LIST*3-12 
%NOCROSS*3-13 
%NOLIST*3-14 
%PAGE*3-15 
%PRINT*3-16 
%SBTTL*3-18 
%TITLE*3-20 
%VARIANT*3-22 
Concatenation 

of  COMMON  areas  *4-28 
string*  1-6,  1-37,  1-40 
Conditional  branching 
IF  statement  *4-1 19 
ON...GOSUB  statement  *  4-205 
ON... GOTO  statement  *  4-207 
SELECT  statement  *  4-283 
Conditional  compilation*  1-8 
with  %IF  directive  *  3-6 
with  %VARIANT  directive  *  3-22 
Conditional  expression*  1-40 
definition  of  *  1  -40 
FOR  statement  *  4-98 
IF  statement  *  4- 1 19 
%LET  directive* 3-10 


Conditional  expression  (cont'd.) 

UNLESS  statement  *  4-3 1 9 
UNTIL  statement  *  4-322 
WHILE  statement  *  4-330 
Conditional  loop  *4-97,  4-323,  4-330 
CON  keyword  *4-164 
CONNECT  clause  *4-2 16 
Constant*  1-24 

declaring*  1-31,  4-43 
default  data  type  *  1  -24 
definition  of*  1-24 
external  *  4-83 
floating-point*  1-25 
integer*  1-27 
lexical  *3-6,  3-10 
named*  1-29 
naming*  1-25,  1-29 
numeric*  1-25 
string*  1-28 
type  of  *  1  -24 

with  OPTION  CONSTANT  TYPE  *4-225 
CONTIGUOUS  clause  *  4-2 1 6 
Continuation  characters 
ampersand*  1-7 
backslash*  1-7 

CONTINUE  debugger  command  *  B-4,  B-5 
Control 

transferring  Into  DEF  functions  *4-205,  4-207 
transferring  into  FOR... NEXT  loops *4-1 16, 
4-118,  4-205,  4-207 

transferring  into  SELECT  blocks  *4-205,  4-207 
transferring  Into  UNTIL  loops  *4-1 16,  4-1 18, 
4-205,  4-207 

transferring  into  WHILE  loops  *4-1 16,  4-118, 
4-205,  4-207 

transferring  to  a  label  *4-1 16,  4-118 
transferring  with  CALL  statement  *  4-8 
transferring  with  CHAIN  statement  *4- 17 
transferring  with  GOSUB  statement  *  4- 1 16 
transferring  with  GOTO  statement  *  4- 1 18 
transferring  with  IF  statement  *  4- 1 19 
transferring  with  ON... GOSUB  statement* 
4-205 

transferring  with  ON... GOTO  statement  *  4-207 
transferring  with  RESUME  statement  *4- 127, 
4-143,  4-273 

transferring  with  RETURN  statement  *4-274 
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Conversion 

array  to  string  variable  •  4-20 
CVT$%  function  •  4-35 
CVT$F  function  •  4-35 
CVT%$  function  •  4-35 
CVTF$  function  •  4-35 
INTEGER  function  *4-133 
NUM 1  $  function  *4-197 
NUM$  function  *4-195 
RAD$  function  *  4-25 1 
REAL  function  *  4-258 
STR$  function  *  4-298 
string  variable  to  array  *4- 19 
VAL%  function  *4-327 
VAL  function  *  4-326 
XLATE$  function  *4-332 
CORE  debugger  command  *B-5,  B-7 
COS  function  *  4-3 1 
Cosine  *  4-3 1 
COUNT  clause  *4-245 

with  fixed-length  records  *  4-325 
with  variable-length  records  *  4-325 
CPU  time  *4-3 14 
Credit-debit  field 

in  PRINT  USING  statement  *  4-237 
%CROSS  directive  *  3-3 
Cross-reference  table 
%CROSS  directive  *  3-3 
%NOCROSS  directive  *3-13 
CTRL/C  function 
trapping  *4-253 
with  RECOUNT  function  *  4-260 
CTRL/C  key  *4-32 
CTRL/Z  function  *  2-29 

with  INPUT  LINE  statement  *  4-128 
with  INPUT  statement  *4- 124 
with  LINPUT  statement  *4- 144 
CTRLC  function  *  4-32 

See  also  RCTRLC  function 
Cursor  position 

CCPOS  function  *4-15 
T AB  function  *  4-3 1 1 
CVT$$  function  *  4-34 
See  also  EDITS  function 
CVTxx  function  *  4-35 

with  FIELD  statement  *  4-86 


D 


Data 

transferring  with  MOVE  statement  *4- 184 
DATA  statement  *  4-38  to  4-39 
See  also  READ  statement 
comment  fields  In*  1-10 
in  DEF*  function  *  4-54 
in  DEF  function  *  4-48 
in  multi-statement  lines*  1-8 
terminating  *4-38 
with  MAT  READ  statement  *4- 174 
with  READ  statement  *  4-256 
with  RESTORE  statement  *  4-270 
Data  type 

integer  overflow*  1-26t 
Data  type  defaults  *  1  - 1 7 
Data  types*  1-13 
BYTE*  1-13,  2-59 
CHARACTER*  1-34 
default*  1-15 

DOUBLE*  1-13,  2-59,  2-60 
floating-point  *2-59,  2-61 
in  LET  statement  *4- 140 
In  logical  expressions*  1-45 
in  numeric  expressions*  1-39 
INTEGER*  1-13 
INTEGER  function  *4-133 
Integer  overflow  *  2-59,  2-60,  2-61 
keywords*  1-13,  1-14 
LONG*  1-13 
LONGWORD*2-60 
numeric  literal  notation*  1-33 
precision*  1-14 

precision  in  PRINT  statement  *  4-234 

precision  in  PRINT  USING  statement  *  4-237 

promotion  rules*  1-39 

range*  1-14 

REAL*  1-13 

REAL  function  *  4-258 

results  in  expressions*  1-39 

RFA*  1-14 

setting  defaults  with  OPTION  statement  *4-225 
SINGLE*  1-13,  2-61 
size*  1-14 

storage  of  *  1-13,  1-14 
STRING*  1-13 
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Data  types  (cont'd.) 

suffix  characters*  1-16 
WORD*  1-13,  2-61 
Data  typing 
explicit*  1-17 
implicit*  1-16 

with  declarative  statements*  1-17 
with  suffix  characters*  1-16 
DATES  function  *  4-40 
Date  and  time  functions 
TIMES  function  *  4-3 1 6 
TIME  function  *  4-3 1 4 
DCL  command 

specifying  from  environment  *  2-2 
Debit-credit  field 

in  PRINT  USING  statement  *  4-237 
Debugger 

breakpoint  disabling* B-25 
breakpoint  setting  *  B-1 
commands  *B-1  to  B-28 
exiting  *  B-10 
Debugger  commands 
BREAK*  B-1 
CONTINUE  *B-5 
CORE*B-5 
ERL*B-8 
ERN  *  B-9 
ERR*B-10 
EXIT  *B- 11 
FREE*  B-1 2 
I/O  BUFFER* B-1 3 
LET*B-14 
PRINT*  B-1 6 
RECOUNT*  B-1 7 
REDIRECT*  B-1 8 
STATUS*  B-1 9 
STEP*B-21 
STRING  *B-23 
TRACE  *B-24 
UNBREAK  *B-26 
UNTRACE  *  B-28 
Decimal  radix*  1-32 
Declarative  statements 

COMMON  statement  *  4-29 
DECLARE  statement  *  4-42 
EXTERNAL  statement  *  4-82 
MAP  statement  *4- 157 
DECLARE  CONSTANT  statement*  1-36 


DECLARE  statement  *  4-42  to  4-45 
CONSTANT*  1-31 
DEF*  function 

error  handling  in  *4-72 
multi-line  *4-52 
parameter  *4-52,  4-53 
recursion  in  *  4-54 
single-line  *4-52 
DEF*  statement  *  4-5 1  to  4-55 
Default 

compiler*  2-70 
data  type*  1-15,  4-225 
environment  *  2-70 
error  handling  *4-199 

parameter-passing  mechanisms  *  4-9  to  4-10t, 
4-84 

scale  factor  *4-225 

setting  with  OPTION  statement  *  4-224 
DEFAULTNAME  clause  *  4-213,  4-216 
DEF  function 
ending  *4-71 

error  handling  in  *4-49,  4-199,  4-201,  4-272 
exiting  *  4-78 
recursion  In  *  4-49 

transferring  control  into  *4-49,  4-205,  4-207 
DEFINE  editing  mode  command  *C-2 
DEF  statement  *  4-46  to  4-50 
multi-line*  4-47 
parameter  *  4-47,  4-48 
single-line  *4-47 

DELETE  command  *  2-22  to  2-23 
DELETE  statement  *  4-56 

with  UNLOCK  statement  *  4-320 
Delimiter 

comma  (,)  *4-233 
double  quotation  mark  (")*  4-233 
in  DATA  statement  *  4-39 
PRINT  statement  *  4-233 
semicolon  (;)*  4-233 
single  quotation  mark  (')*  4-233 
string  literal  *  1-28 
Descriptor  *4- 12,  4-85,  4-303 
Determinant  *  4-58 
DET  function  *  4-58 
DIF$  function  *  4-60 
DIMENSION  statement  *  4-62  to  4-66 
executable  *4-63,  4-65 
nonexecutable  *  4-63 
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DIMENSION  statement  (cont'd.) 
nonvirtual  •  4-63 
virtual  •  4-63 

with  MAT  statement  *4- 163,  4-166,  4-168, 
4-172,  4-174 
Documentation 
program  •  1  -9 
Dollar  sign  ($) 

in  DECLARE  statement  •  4-43 
in  DEF*  statement  names  •  4-5 1 
in  DEF  names  *4-46 
in  PRINT  USING  statement  •  4-238 
In  variable  names*  1-18,  1-19 
suffix  character  *1-16 
DOUBLE  data  type*  1-13 
DSKLIB  command  *  2-24 
DUPLICATES  clause  *4-221,  4-247 
Dynamic  array  *4-62,  4-63,  4-65 
Dynamic  mapping  *  4-86,  4-159,  4-264 
Dynamic  storage  *4- 159,  4-264,  4-266 


E 


ECHO  function  *  4-67 

See  also  NOECHO  function 
EDITS  function  *  4-69 
values  *  4-69  to  4-70t 
EDIT  command  *  2-26  to  2-28 

editing  mode  commands  *2-26,  C-2  to  C-1 1 
Editing  mode  *2-26 

adding  program  lines  *C-7 
exiting  *  C-4 
locating  string  *  C-6 
string  substitution  *  C-9 
Editing  mode  commands* C-2  to  C-1 1 
DEFINE*  C-2 
EXECUTE  *C-3 
EXIT*  C-4 
FIND*  C-6 
INSERT  *C-7 
SUBSTITUTE*  C-9 
E  formatting  character 

in  PRINT  USING  statement  *  4-240 
ELSE  clause  *4-1 19 
E  mathematical  constant  *  4-80 
END  statement  *  4-7 1  to  4-73 
SUB  subprograms  *  4-303 


E  notation  *  1-26 

See  Exponential  notation 
field  in  PRINT  USING  statement  *4-237 
numbers  In*  1-26t 
with  STR$  function  *  4-298 
Environment 

online  help  *2-32 

Environment  commands  *2-1  to  2-80 
APPEND  *2-4 
BRLRES*2-6 
BUILD  *2-9 
DELETE  *2-22 
DSKLIB  *2-24 
EDIT  *2-26 
EXIT  *2-29 
EXTRACT  *2-30 
HELP  *2-32 
IDENTIFY  *2-34 
INQUIRE  *2-35 
LIBRARY  *2-35 
LIST  *2-38 
LISTNH  *  2-38 
LOAD  *2-40 
LOCK  *2-42 
NEW  *2-43 
ODLRMS*2-45 
OLD  *2-48 
RENAME  *2-50 
REPLACE  *  2-52 
RMSRES*2-54 
RUN  *2-57 
SAVE  *  2-63 
SCALE  *  2-65 
SCRATCH  *  2-67 
SEQUENCE  *  2-68 
SET  *2-70 
SHOW  *2-78 
$  system-command  *  2-2 
UNSAVE  *  2-80 

ERL  debugger  command  *  B-7,  B-8 
ERL  function  *  4-74 

/[NO]LINE  qualifier  *4-74 
with  labels*  1-3 
ERN$  function  *  4-75 
ERN  debugger  command  *  B-8,  B-9 
ERR  debugger  command* B-9,  B-10 
ERR  function  *4-76 
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Error  handling 

determining  error  number  *6-9 

determining  line  number  *6-7 

determining  program  name*B-8 

disabling  •  4-203 

ERL  command  •  B-7 

ERL  function  •  4-74 

ERN$  function  *4-75 

ERN  command  •  B-8 

ERR  command  •  B-9 

ERR  function  *4-76 

ERT$  function  *4-7  7 

in  DEF  functions  *4-49,  4-72,  4-199,  4-201 
in  FOR.. .NEXT  loops *4-273 
in  subprograms  *4-72,  4-79,  4-105,  4-199 
in  UNTIL  loops  *4-273 
in  WHILE  loops  *4-273 
ON  ERROR  GO  BACK  statement  *4- 199 
ON  ERROR  GOTO  0  statement  *  4-203 
ON  ERROR  GOTO  statement  *4-201 
recursion  in  *4-201 
RESUME  statement  *4-272 
Error  handling  functions 
CTRLC  function  *  4-32 
ERL  function  *4-74 
ERN$  function  *4-75 
ERR  function  *4-76 
ERT$  function  *  4-77 
RCTRLC  function  *  4-253 
Error  number 

displaying  *4-76 
Error  text 

displaying  *4-77 
ERT$  function  *  4-77 
Evaluation 

of  expressions  *  1  -48 
of  logical  expressions*  1-46 
of  numeric  relational  expressions*  1-41 
of  operators  *  1  -49 
of  SELECT  statement  *  4-285 
of  string  relational  expressions*  1-42 
Exclamation  point  (!) 

in  comment  fields*  1-9 
in  PRINT  USING  statement  *  4-240 
Executable  statement*  1-3 
EXECUTE  editing  mode  command  *C-3 


Execution 

continuing  *  B-4 
of  multi-statement  lines*  1-6 
of  statements  *  1  -6 
of  system  commands  *  2-2 
program  *  2-57 
resume*  2-58 
stopping  *2-58,  4-296,  B-1 
stopping  to  debug  *  B-20 
suspending  *  4-290,  4-328 
tracing  program  *  B-23 
EXIT  command  *2-29 
EXIT  debugger  command  *  B-1 0,  B-1 1 
EXIT  editing  mode  command  *C-4 
EXIT  statement  *4-78  to  4-79 
EXP  function  *  4-80 
Explicit 

creation  of  arrays  *  4-62 
data  typing*  1-17,  4-224 
declaration  of  variables*  1-20 
literal  notation*  1-32 
loop  iteration  *4- 135 
record  locking  *4-56,  4-112 
Exponential  notation*  1-26 

In  PRINT  USING  statement  *4-237 
numbers  in*  1-26t 
PRINT  statement  *  4-233 
Exponentiation  *  4-80 
Expressions*  1-37 
conditional*  1-40 

conditional  In  %LET  directive* 3-10 
definition  of*  1-37 
evaluation  of*  1-48 
lexical  *3-7,  3-10,  3-22 
logical  *  1-44 
mixed-mode*  1-39 
numeric*  1-37 
numeric  relational*  1-41 
operator  precedence  In*  1-49 
parentheses  in*  1-49 
relational  *  1-41 
string  *  1  -40 
string  relational*  1-42 
types  of*  1-37 
Extended  field 

in  PRINT  USING  statement  *  4-240 
EXTENDSIZE  clause  *4-2 17 
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External 

constant  •  4-83 
function  •  4-83 
subprogram  *4- 105 
subroutine  •  4-83 
variable  •  4-83 
External  constants*  1-31 
naming*  1-32 

EXTERNAL  CONSTANT  statement*  1-31 
EXTERNAL  statement  *  4-82  to  4-85 
parameter  *  4-83 
External  variables 
naming*  1-19 
EXTRACT  command  *  2-30 


F 


Field 

asterisk-filled  *  4-238 
blank-if-zero  *  4-238 
centered  *  4-240 
comment*  1-9 
credit  or  debit  *4-237 
exponential  *4-237 
extended  *  4-240 
floating  dollar  sign  *  4-238 
left-justified  *  4-240 

multiple  fields  within  a  format  string  *  4-238 
one-character  *  4-240 
right-justified  *  4-240 
trailing  minus  sign  *4-237 
zero-filled  *  4-238 
FIELD  statement  *  4-86  to  4-87 
File 

accessing  *4- 109 

block  1/0*4-91,4-112,  4-2 1 8 

closing  *  4-23 

deleting  *  2-80,  4-136 

deleting  records  in  *  4-56 

finding  buffer  size  *  4-7 

%INCLUDE*3-8 

indexed  *4-56,  4-91,  4-112,  4-215,  4-217, 
4-218 

locating  *  4-87 

magnetic  tape  *4-153,4-215 
0DL*2-44,  2-46 
opening  *  4-2 1 1 


File  (cont'd.) 

relative  *  4-56,  4-91,4-112,4-215,4-218 
renaming  *4- 188 

retrieving  information  about  *B- 18 
sequential  *  4-9 1,4-112,  4-2 1 8 
terminal-format  *4- 122,  4-126,  4-142,  4-166, 
4-168,4-171 
File  attributes 

BLOCKSIZE  clause  *4-2 15 
CONTIGUOUS  clause  *  4-2 1 6 
EXTENDSIZE  clause  *4-2 17 
FILESIZE  clause  *  4-2 1 7 
magnetic  tape  *  4-2 1 5 
File  organization 
indexed  *4-2 19 
relative  *  4-2 1 9 
sequential  *4-2 19 
undefined  *  4-2 1 9 
virtual  *  4-2 1 9 
File-related  functions 
BUFSIZ  function  *  4-7 
CCPOS  function  *4-15 
FSP$  function  *4-101 
GETRF A  function  *4-114 
RECOUNT  function  *  4-260 
STATUS  function  *  4-293 
Files 

block  I/O  *  4-246 
deleting  *  4-222 
deleting  records  in  *  4-280 
indexed  *4-246,  4-270,  4-325 
magnetic  tape  *  4-270 
relative  *4-222,  4-246,  4-325 
restoring  data  *4-270 
sequential  *4-222,  4-232,  4-246,  4-280 
4-325 

terminal-format  *4-221,  4-222,  4-232 
virtual  *4-222,  4-271 
FILESIZE  clause  *  4-2 1 7 
FILL  keywords  *  4-26 

In  MAP  statement  *4- 157 
in  MOVE  statement  *4- 185 
in  REMAP  statement  *  4-265 
FIND  editing  mode  command  *  C-6 
FIND  statement  *  4-88  to  4-92 
with  UNLOCK  statement  *  4-320 
with  UPDATE  statement  *  4-324 
FIX  function  *  4-93 
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FIX  function  (cont'd.) 

compared  with  INT  function  *4- 132 
Floating  dollar  sign  field 

In  PRINT  USING  statement  •  4-238 
Floating-point 

constants*  1-25 
data  types*  1-13 
overflow*  1-37 
promotion  rules*  1-39 
variables*  1-19 
FNEND  statement  *  4-94 
See  also  END  statement 
FNEXIT  statement  *4-95 
See  also  EXIT  statement 
FOR... NEXT  loops *4-96  to  4-99,  4-190 
conditional  *  4-97 
error  handling  in  *4-273 
explicit  Iteration  of  *4- 135 
nested  *  4-97 

transferring  control  Into  *4-98,  4-116,  4-118, 
4-205,  4-207 
unconditional  *  4-97 
F0R_NEXT  loops 
exiting  *4-79 
FOR  clause  *4-2 13 
Format 

characters  in  PRINT  USING  statement* 4-237 
combination  of  characters  in  PRINT  USING 
statement  *  4-238 
E-format  *4-233 
exponential  *  4-233 
FILL  *4-26 

multiple  print  fields  with  PRINT  USING 
statement  *  4-238 
of  data  in  DAT  A  statement  *  4-39 
of  keywords  *1-4 
of  labels  *1-2 

of  multi-line  REM  statement  *4-262 
of  multi-statement  lines*  1-7,  1-8 
of  program  lines*  1-1 
of  statements*  1-3 
Radix-50  *4-251 
FORMATS  function  *4- 100 
FOR  statement  *  4-96  to  4-99 
FREE  debugger  command  *  B- 1 1 ,  B- 1 2 
FSP$  function  *4- 101 
FSS$  function  *4-103 


Function 

built-in  *  3-6,  3-10,  3-22 
declaring  *  4-43,  4-46,  4-51 
external  *  4-83 
Initialization  of  *4-49,  4-54 
Invocation  of  *4-48,  4-53 
lexical  *3-6,  3-10,  3-22 
naming *4-46,  4-51 
parameter  *  4-47,  4-52 
user-defined  *  4-46,  4-5 1 
FUNCTIONEND  statement  *  4-107 
See  also  END  statement 
FUNCTIONEXIT  statement  *  4- 1 08 
See  also  EXIT  statement 
Functions 
ABS*4-2 
ABS%*4-4 
ASCII  *4-5 
ATN  *  4-6 
BUFSIZ*4-7 
CCPOS*4-15 
CHR$  *  4-22 
COMP%*4-30 
COS  *4-31 
CTRLC*4-32 
CVT$$*4-34 
CVTxx*4-35 
DATES  *4-40 
DET*4-58 
DIFS  *4-60 
ECHO  *4-67 
EDITS  *  4-69 
ERL  *4-74 
ERNS*4-75 
ERR  *4-76 
ERTS*4-77 
EXP  *4-80 
FIX  *4-93 
FORMATS  *4- 100 
FSPS*  4-101 
FSSS*4-103 
GETRFA*4-114 
INSTR*4-129 
INT*4-131 
INTEGER  *4- 133 
LEFTS  *4- 137 
LEN*4-139 
LOG  *4- 145 
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Functions  (cont'd.) 

LOG10«4-147 
MAG*4-151 
MAGTAPE  •4- 153 
MAX  *4- 176 
MID$*4-178 
MIN  •4- 180 
MOD  *4-182 
NOECHO *4- 192 
NUM*4-193 
NUM1$*4-197 
NUM2*4-194 
NUM$*4-195 
ONECHR*  4-209 
PLACES  *4-227 
POS*  4-230 
PRODS  *  4-242 
QUOS  *  4-249 
RADS  *4-251 
RCTRLC*  4-253 
RCTRLO*  4-254 
REAL  *4-258 
RECOUNT  *4-260 
RIGHTS  *4-275 
RND*  4-277 
SEGS*  4-281 
SGN  *  4-288 
SIN  *4-289 
SPACES  *4-291 
SQR*  4-292 
STATUS  *4-293 
STRS*  4-298 
STRINGS  *  4-300 
SUMS  *4-307 
SWAP%  *  4-309 
SYS  *4-3 10 
TAB  *4-3 11 
TAN  *4-3 13 
TIME  *4-3 14 
TIMES  *4-3 16 
TRMS*4-318 
VAL*  4-326 
VAL%*  4-327 
XLATES  *  4-332 

FUNCTION  statement  *4-104  to  4- 1 06 

FUNCTION  subprogram 
parameter  *4- 104 


FUNCTION  subprograms 
naming  *4- 104 


G 


GETRFA  function  *4-1 14 
GET  statement  •4- 109  to  4-1 13 
with  UNLOCK  statement  •  4-320 
with  UPDATE  statement  •  4-324 
GOSUB  statement  *4-116 

with  RETURN  statement  •  4-274 
GOTO  statement  *4-1 18 


H 


HELP  command  •  2-32  to  2-33 
Hexadecimal  radix*  1-32 
Hyphen  (-) 

in  DELETE  command  *  2-22 
in  EXTRACT  command  *2-30 
in  LIST  command  *  2-38 


I 


I/O 

buffer  space  *B- 12 
characters  transferred  *  4-260 
closing  files  *4-23,  4-72 
deleting  records  *  4-56 
determining  character  transfer  *  B- 1 6 
directing  *B- 17 
dynamic  mapping  *  4-264 
finding  records  *  4-89 
matrix  *4- 193,  4-194 
moving  data  *4- 184 
opening  files  *4-21 1 
retrieving  records  *  4-1 1 1 
unlocking  records  *  4-320 
updating  records  *  4-324 
with  CHAIN  statement  *4- 18 
writing  records  *  4-246 
I/O  BUFFER  debugger  command  *  B- 12,  B-13 
%IDENT  directive  *  3-4,  3-5 
IDENTIFY  command  *2-34 
Identity  matrix  *4-164 
IDN  keyword  *4-164 

IF... THEN... ELSE  statement  *  4- 1 19  to  4-121 
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IF... THEN... ELSE  statement  (cont'd.) 
labels  in*  1-3 
multi-line  format*  1-7 

%IF-%THEN-%ELSE-%END  %IF  directive* 3-6,  3-7 

Immediate  hriode*2-58 

Implicit 

continuation  of  lines*  1-7 
creation  of  arrays  *4-64,  4-163,  4-166,  4-168, 
4-172,  4-174 
data  typing*  1-16 
declaration  of  variables*  1-19 
%INCLUDE  directive  *  3-9 
Indexed  files  *4-2 19 

ALTERNATE  KEY  clause  *  4-220 
BUCKETSIZE  clause  *  4-2 1 5 
CHANGES  clause  *4-221 
deleting  records  in  *  4-56 
DUPLICATES  clause  *4-221 
finding  records  in  *  4-9 1 
MAP  clause  *4-2 17 
opening  *  4-2 1 8 
PRIMARY  KEY  clause  *4-220 
restoring  data  in  *4-270 
retrieving  records  sequentially  in  *4-1 12 
segmented  keys  in  *  4-220 
updating  *4-325 
writing  records  to  *  4-246 
Initialization 

in  subprograms  *  4-105,  4-303 
of  arrays* 4-164 
of  DEF»  functions  *  4-54 
of  DEF  functions  *  4-49 
of  dynamic  arrays  *  4-65 
of  variables*  1-23,  4-44 
of  variables  In  COMMON  statement  *  4-29 
of  virtual  arrays  *  4-65 
INPUT  LINE  statement  *4- 126  to  4-128 
INPUT  statement  *4- 122  to  4-125 
INOUIRE  command  *  2-35 
INSERT  editing  mode  command  *  C-7 
INSTR  function  *4- 129  to  4-130 
See  also  POS  function 
Integer 

constants*  1-27 
data  types*  1-13 
overflow*  1-37,  4-45 
promotion  rules*  1-39 
suffix  character*  1-16 


Integer  (cont'd.) 

variables*  1-20 
INTEGER  data  type  *1-13 
INTEGER  function  *4- 133 
Integer  overflow*  1-26t 
loop  variable  *  4-97 
Internal  variables 
naming*  1-18 
INT  function  *4-1 31 
INV  keyword  *  4-165 
ITERATE  statement  *4- 135 
Iteration 

of  FOR  loops  *  4-98 
of  loops* 4-135 
of  UNTIL  loops  *4-322 
of  WHILE  loops  *4-331 


K 


KEY  clause  •4-89,  4-110 
FIND  statement  *  4-89 
GET  statement* 4-1 10 
RESTORE  statement  *4-270 
segmented  keys  *  4-220 
Keywords 

data  type*  1-13 
definition  of  *  1-4 
function  of  *  1  -4 
list  of  *  A-1  to  A- 10 
reserved  and  unreserved  *  A-1 
restrictions*  1-4 
spacing  requirements*  1-4 
VAX  BASIC*  A-9 
KILL  statement  *4-136 


L 


Labels 

defining*  1-3 
format  of  *  1  -2 
function  of*  1-2,  1-3 
referencing*  1-3 

transferring  control  to  *4-1 16,  4-118 
with  ITERATE  statement* 4-135 
LEFTS  function  *4- 137 
See  also  SEG$  function 
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Left-justification 

PRINT  USING  statement  •  4-240 
with  LSET  statement  *4- 149 
LEN  function  *4- 139 
Length 

of  labels*  1-2 
of  STRING  data*  1-14 
variable  names*  1-18 
LET  debugger  command  *B- 13,  B-15 
%LET  directive  *3- 10,  3-11 
LET  statement  *4- 140 
Letters 

lowercase*  1-12,  2-27,  4-240 
uppercase*  1-12,  2-27,  4-240 
Lexical 

constants  *  3-6,  3-10 

assigning  values  to  *3- 10 
naming  *3- 10 

expressions  *3-7,  3-10,  3-22 
functions  *  3-6,  3-10,  3-22 
operators  *  3-6,  3-10 
order*  1-12 
L  formatting  character 

in  PRINT  USING  statement  *  4-240 
Library 

memory-resident  *2-7,  2-35,  2-53 

object  module  *  2-24 

RMS  *2-46 

specifying  *  2-6,  2-35 

types  *  2-7 

LIBRARY  command  *2-35 
Line  numbers 

generating  *  2-68 
in  %INCLUDE  file  *3-8 
of  error  *  B-7 
tracing  *  B-23 
Lines 

continuing*  1-6 
elements  of*  1-1 
format  of  *  1  - 1 
multi-statement*  1-6 
order  of  *  1  - 1 2 
single-statement*  1-5 
terminating*  1-12,  1-13 
Line  terminator*  1-12,  1-13 
with  DATA  statement  *  4-38 
with  INPUT  LINE  statement  *  4-127 
with  INPUT  statement  *4- 123 


Line  terminator  (cont'd.) 

with  LINPUT  statement  *4- 143 
LINPUT  statement  *4- 142  to  4-144 
LIST  command  *  2-38  to  2-39 
%LIST  directive  *3- 12 
Listing  file 

control  of*  1-8,  3-3,  3-12,  3-13,  3-14,  3-15 

%CROSS  directive  *  3-3 

default  *2-15 

included  code  *  3-8 

line  numbers*  1-7 

%LIST  directive  *3- 12 

%NOCROSS  directive  *3- 13 

%NOLIST  directive  *  3- 1 4 

%PAGE  directive  *3-15 

%PRINT  directive  *3- 16 

%SBTTL  directive  *3-18 

subtitle  *3- 18 

title  *3-20 

%TITLE  directive  *  3-20 
version  identification  *  3-4 
LISTNH  command  *  2-38 
Literal 

explicit  notation*  1-32 
numeric*  1-25 

string*  1-6,  1-12,  1-28,  1-44,  4-238,  4-240 
LOAD  command  *  2-40  to  2-41 
with  RUN  command  *  2-58 
with  SCRATCH  command  *2-67 
Local  copy  *  4- 1 2 
LOCK  command  *  2-42 
LOG  1 0  function  *4-147 
Logarithms 

common  *4- 147 
natural  *4- 145 
LOG  function  *4-145 
Logical  expressions*  1-44 

compared  with  relational*  1-45,  1-46 
data  types  In*  1-45 
definition  of*  1-40 
evaluation  of*  1-46 
format  of  *  1  -44 
logical  operators*  1-45 
truth  tables  *  1  -46 
truth  tests  *  1  -46 
Logical  operators*  1-45 
LONG  data  type*  1-13 
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Loop 

conditional  •  4-97 
exiting  *4-78 
F0R...NEXT«4-96 
integer  overflow  •  4-97 
iteration  of  *4-98,  4-135 
nested  FOR...NEXT®4-97 
single-line*  4-330 
unconditional  •  4-97 
Loops 

iteration  of  *4-322,  4-331 
UNTIL  statement  *4-322 
WHILE  statement  *4-330 
Lowercase  letters 

in  EDIT  command  *2-27 
in  PRINT  USING  statement  *  4-240 
processing  of  *  1-12 
LSET  statement  *  4- 1 49 


M 


Macro  definition 
creating  *  C-2 
executing  *  C-3 
Macro  subprogram 

passing  mechanism  *  4-8 
MAG  function  *4-151 
Magnetic  tape  files 

BLOCKSIZE  clause  *4-2 15 
MAGTAPE  function  *4-153 
NOREWIND  clause  *4-2 18 
RESTORE  statement  *4-270 
MAGTAPE  function  *  4- 1 53  to  4- 1 55 
MAP 

area  *4- 156 

FILL  format  and  storage  *  4-28 
Map 

allocation  *4- 158 
size  *4- 158 

MAP  clause  *4- 158,  4-217 
MAP  DYNAMIC  statement* 4-159  to  4-161 
with  REMAP  statement  *  4-264,  4-266 
MAP  statement  *4-156  to  4- 1 58 
FILL  keywords  *  4-26 
with  FIELD  statement  *  4-87 
with  MAP  DYNAMIC  statement* 4-161 
with  REMAP  statement  *  4-264 


MAT  INPUT  statement  *4- 166  to  4-167 
MAT  LINPUT  statement  *4- 168  to  4-170 
MAT  PRINT  statement  *4-1 71  to  4-173 
MAT  READ  statement  *4- 174  to  4-175 
Matrix*  1-22 

arithmetic  *4- 164 

assigning  values  *4- 166,  4-168,  4-174 
functions 

DET  function  *  4-58 
NUM2  function  *4- 194 
NUM  function  *4- 193 
1/0*4-193,  4-194 
identity  *4-164 
Inversion  *4-58,  4-165 
printing  *4-1 71 

redimensioning  *4- 166,  4-168,  4-171, 4-174 
scalar  multiplication  *4- 164 
transposition  *4-165 
MAT  statement  *4- 162  to  4-165 
with  DET  function  *  4-58 
with  FIELD  statement  *  4-87 
MAX  function  *  4- 1 76  to  4- 1 77 
Memory 

allocation  *  B-5,  B-11,  B-12,  B-22 
available*  B-1 1 
clearing  *  2-67 
extending*  B-1 1 
overlaying  *  4-28 
Memory-resident  library 
default  *  2-36 
selecting  *  2-53 
MID$  function  *4-178 
See  also  SEG$  function 
MIN  function  *  4- 1 80  to  4- 1 8 1 
Minus  sign  (-) 

in  PRINT  USING  statement  *  4-237 
Mixed-mode  expressions*  1-39 
MODE  clause  *4-2 18 
MOD  function  *4-182  to  4- 1 83 
Modifiable  parameters  *4-1 1 
Modifiers 

FOR  statement  *  4-96 
IF  statement  *4-1 19 
UNLESS  statement  *  4-3 1 9 
UNTIL  statement  *4-323 
WHILE  statement  *4-331 
MOVE  statement  *4- 184  to  4-187 
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MOVE  statement  (cont'd.) 

FILL  keywords  •  4-26 
with  FIELD  statement  •4-87 
Multi-line 

DEF*  functions  •  4-52 
DEF  statement  •  4-47 
Multi-statement  lines*  1-6 
backslash  in*  1-6 
branching  to*  1-7 
execution  of*  1-6 
format  of  *  1-7,  1-8 
implicit  continuation*  1-7 
transferring  control  to*  1-6 


N 


NAME... AS  statement  *  4- 1 88 
Named  constants*  1-29 
changing*  1-29 
external*  1-31,  4-83 
internal*  1-30,  4-43 
NEW  command  *  2-43  to  2-44 
NEXT  statement  *4- 190 
with  FOR  statement  *  4-98 
with  WHILE  statement  *  4-330 
[N0]SPAN  clause  *4-2 18 
%NOCROSS  directive  *3- 13 
NOECHO  function  *4-192 
See  also  ECHO  function 
%NOLIST  directive* 3-14 
Nonexecutable  statements*  1-3,  1-12 
COMMON  statement  *  4-28 
DATA  statement  *  4-39 
DECLARE  statement  *  4-44 
EXTERNAL  statement  *  4-84 
MAP  DYNAMIC  statement  *  4- 1 60 
MAP  statement  *4-157 
REM  statement  *  4-262 
UNLESS  statement  *  4-3 1 9 
Nonmodifiable  parameters  *4-12 
Nonprinting  characters 
processing  of  *  1-12 
using*  1-12 

NOREWIND  clause  *  4-2 1 8 
Notation 

E*  1-26,  1-26t,  4-237,  4-239 
explicit  literal*  1-32 


Notation  (cont'd.) 

exponential*  1-26,  4-233 
NOT  operator 

evaluation  of*  1-50 
NUL$  key  word  *  4- 1 64 
NUM 1  $  function  *4-197 
NUM2  function  *4-194 

after  MAT  INPUT  statement  *4- 167 
after  MAT  LINPUT  statement  *4- 169 
after  MAT  READ  statement  *4- 175 
NUM$  function  *4-195 
Number 

E  notation*  1-26t 
random  *4-252,  4-277 
sign  *  4-288 
Number  sign  (#) 

in  PRINT  USING  statement  *4-237 
Numeric  constants*  1-25 
Numeric  conversion  *  4-20 
Numeric  expressions*  1-37 
format  of  *  1  -38 
promotion  rules*  1-39 
result  data  types*  1-39 
Numeric  functions  *  4-35 
ABS%  function  *  4-4 
ABS  function  *  4-2 
FIX  function  *  4-93 
INT  function  *4-131 
LOG  1 0  function  *4-147 
LOG  function  *4-145 
MAG  function  *4-151 
RND  function  *  4-277 
SGN  function  *  4-288 
SQR  function  *  4-292 
SWAP%  function  *  4-309 
Numeric  literal  notation*  1-32 
Numeric  operator  precedence*  1-49 
Numeric  precision 

with  PRINT  statement  *  4-234 
with  PRINT  USING  statement  *  4-237 
Numeric  relational  expressions 
evaluation  of  *  1-41 
operators  *1-41 
Numeric  string  functions 
CHR$  function  *  4-22 
COMP%  function  *  4-30 
DIF$  function  *  4-60 
FORMATS  function  *4-100 
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Numeric  string  functions  (cont'd.) 

INTEGER  function  *4- 133 
NUM 1  $  function  •4-197 
NUM$  function  *4-195 
PLACES  function  •  4-227 
PRODS  function  •  4-242 
QUOS  function  *4-249 
REAL  function  *  4-258 
SIRS  function  *4-298 
SUMS  function  *  4-307 
VAL%  function  *  4-327 
VAL  function  *  4-326 
Numeric  strings 
comparing  *  4-30 

precision  *  4-60,  4-227,  4-242,  4-249,  4-307 
rounding  *  4-227,  4-242,  4-249 
rounding  and  truncation  values  *4-228  to 
4-229t 

truncating  *4-227,  4-242,  4-249 
NUM  function  *4- 193 

after  MAT  INPUT  statement* 4-167 
after  MAT  LINPUT  statement* 4-169 
after  MAT  READ  statement  *4-1 75 


0 


Object  module 
creating  *2- 15 
default  *2- 15 
loading  *  2-40 
version  identification  *  3-4 
Object  module  library 
default  *2-24,  2-36 
disk-resident  *2-25 
selecting  *  2-24 

Object  Time  System  (OTS)  routines 
See  OTS  routines 
Octal  radix*  1-32 
ODL  file 

file  name  *  2-46 
name*  2-46 
RMS  library  *2-46 
selecting  *  2-44 
type  of  *  2-46 
ODLRMS  command  *  2-44 
OLD  command  *  2-48  to  2-49 
ON. .  .GOSUB. . .OTHERWISE  statement  *  4-205 


ON. ..GOSUB.. .OTHERWISE  statement  (cont'd.) 

with  RETURN  statement* 4-274 
ON... GOSUB  statement  *  4-205  to  4-206 
ON . .  .GOTO. .  .OTHERWISE  statement  *  4-207 
ON. ..GOTO  statement *4-207  to  4-208 
ONECHR  function  *  4-209  to  4-210 
ON  ERROR  GO  BACK  statement  *4- 199  to  4-200 
with  END  statement  *4-72 
within  a  handler  *4- 199 

ON  ERROR  GOTO  0  statement  *  4-203  to  4-204 
with  END  statement  *4-72 
ON  ERROR  GOTO  statement  *  4-201  to  4-202 
with  END  statement  *4-72 
within  a  handler  *4-201,  4-203 
Online  help* 2-32 
Opening  files 

with  USEROPEN  clause  *4-222 
OPEN  statement  *4-21 1  to  4-223 
with  STATUS  function  *  4-293 
Operator  precedence*  1-37,  1-49 
Operators 

arithmetic*  1-37,  1-38 
evaluation  of*  1-49 
lexical  *  3-6,  3-10 
logical*  1-45 

numeric  operator  precedence*  1-49 
numeric  relational*  1-41 
precedence  of*  1-37,  1-49 
string  relational*  1-43 
OPTION  statement  *  4-224  to  4-226 
ORGANIZATION  clause  *4-2 18 
OTHERWISE  clause  *4-205,  4-207 
OTS  routines  *D-1  to  D-1 1 
Output 

formatting  with  FORMATS  function  *  4-100 
formatting  with  PRINT  USING  statement* 
4-236  to  4-240 
Output  listing 

cross-reference  table  *3-3,  3-13 
%LIST  directive  *3- 12 
%NOLIST  directive  *3- 14 
%PAGE  directive  *3- 15 
%PRINT  directive  *3- 16 
%SBTTL  directive  *3- 18 
%TITLE  directive  *  3-20 
Overflow  checking*  1-37,  4-45 
Overlay  Description  Language  file 
See  ODL  file 
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%PAGE  directive  *3- 15 
Parameter 

DEF*  function  •  4-52,  4-53 
DEF  statement  *4-47,  4-48 
EXTERNAL  statement  •  4-83 
function  *4-47,  4-52 
FUNCTION  subprogram  *4- 104 
modifiable  *4-1 1 
nonmodifiable*4-12 
SUB  subprogram  •  4-302 
Parameter-passing  mechanisms 
BASIC-PLUS-2  •  4-9  to  4-10t 
CALL  statement  •  4-8 
DEF*  function  •  4-53 
DEF  statement  •  4-48 
EXTERNAL  statement  •  4-84 
SUB  statement  •  4-303 
Parentheses 

in  array  names*  1-21 
in  expressions*  1-37,  1-49 
Passing  mechanisms 

See  parameter-passing  mechanisms 
Percent  sign  (%) 

in  DATA  statement*  1-28,  4-38 
in  DECLARE  statement  *  4-43 
in  PRINT  USING  statement  *  4-238 
in  variable  names*  1-18,  1-19 
suffix  character*  1-16 
Period  (.) 

in  PRINT  USING  statement  *4-237 
in  variable  names*  1-19 
PLACES  function  *4-227  to  4-229t 

rounding  and  truncation  values  *  4-228  to 
4-229t 
Plus  sign  (+) 

in  string  concatenation*  1-40 
POS  function  *  4-230  to  4-23 1 
Precision 

in  PRINT  statement  *  4-234 
in  PRINT  USING  statement  *  4-237 
NUMIS  function  *4- 197 
NUM$  function  *4-195 
of  data  types  *  1  - 1 4 

of  numeric  strings  *  4-60,  4-227,  4-242,  4- 
249,  4-307 


Predefined  constants*  1-35 
PRIMARY  KEY  clause  *4-220 
PRINT  debugger  command* B- 15,  B-16 
%PRINT  directive  *3- 16,  3-17 
PRINT  statement  *  4-232  to  4-235 
with  TAB  function  *  4-3 1 1 
PRINT  USING  statement  *  4-236  to  4-241 
Print  zones 

In  MAT  PRINT  statement  *  4- 1 7 1 
PRINT  statement  *  4-233 
PRODS  function  *  4-242  to  4-243 

rounding  and  truncation  values  *  4-228  to 
4-229t 
Program 

appending  *2-3 
breakpoint  disabling  *B-25 
breakpoint  setting  *B-1,  B-2 
compiling  *2- 15 
continuing  *  2-58 
debugging  *2-58 
deleting  *  2-80 
documentation  *  1  -9 
elements*  1-1 
ending  *4-71 

environment  editing  *  2-26,  2-48 
environment  editing  commands  *C-2 
executing  *  2-57 
library  *2-24 
naming  *  2-43 
passing-mechanism  *  4-8 
renaming  *  2-50 
replacing  *  2-52 
saving  *  2-63 
stopping  *  2-58,  4-296 
Program  control  statements 
END  statement  *  4-7 1 
EXIT  statement  *4-78 
FOR  statement  *  4-96 
GOSUB  statement  *4-116 
GOTO  statement  *4-118 
IF  statement  *  4- 1 19 
ITERATE  statement  *4- 135 
ON... GOSUB  statement  *  4-205 
ON... GOTO  statement  *  4-207 
RESUME  statement  *4-272 
RETURN  statement  *4-274 
SELECT  statement  *  4-283 
SLEEP  statement  *  4-290 


Index- 17 


Program  control  statements  (cont'd.) 
STOP  statement  •  4-296 
UNTIL  statement  •  4-322 
WAIT  statement  •  4-328 
WHILE  statement  •  4-330 
Program  execution 

continuing  *2-58,  B-4 
disabling  breakpoints* B-25 
initiating*  2-57 
setting  breakpoints* B-1,  B-2 
stopping  *2-58,  4-296,  B-28 
stopping  for  debugging  *  B-20 
suspending  *4-290 
tracing  *  B-23 
waiting  for  input  *  4-328 
Program  input 

INPUT  LINE  statement  *4- 126 
INPUT  statement  *4- 122 
LINPUT*4-142 
waiting  for  *4-328 
Program  lines 
deleting  *  2-22 
displaying  *  2-38 
elements  of  *  1-1 
environment  editing  *  2-26 
extracting  *  2-30 
format  of  *  1  - 1 
numbering*  1-2 
order  of  *  1-12 
terminating*  1-12,  1-13 
PROGRAM  statement  *  4-244 
Promotion  rules 
data  type  *  1  -39 
floating-point*  1-39 
integer*  1-39 
Prompt 

after  STOP  statement  *  4-296 
INPUT  LINE  statement  *4- 126 
INPUT  statement  *4- 122 
LINPUT  statement  *4- 142 
MAT  INPUT  statement  *4- 167 
MAT  LINPUT  statement  *4- 169 
PSECT*4-25,  4-28,  4-156 
PUT  statement  *4-245  to  4-248 


Q 


QUO$  function  *  4-249  to  4-250 

rounding  and  truncation  values  *  4-228  to 
4-229t 

Quotation  marks 

in  string  literals*  1-28 


R 


RAD$  function  *  4-25 1 
Radix 

ASCII*  1-32 
binary*  1-32 
decimal  *  1-32 
default*  1-32 
hexadecimal*  1-32 
in  explicit  literal  notation*  1-32 
octal*  1-32 
RAD-50*  1-32 
Radix-50  *4-251 
RANDOMIZE  statement  *  4-252 
See  also  RND  statement 
Random  numbers  *4-252,  4-277 
Range 

of  data  types*  1-14 
of  subscripts*  1-21 
RCTRLC  function  *  4-253 

See  also  CTRLC  function  *  4-253 
RCTRLO  function  *  4-254  to  4-255 
READ  statement  *  4-256  to  4-257 
See  also  DATA  statement 
with  DATA  statement  *4-38,  4-39 
REAL  data  type*  1-13 
REAL  function  *  4-258  to  4-259 
Record  attributes 
MAP  clause  *4-2 17 
RECORDSIZE  clause  *4-2 17,  4-221 
RECORDTYPE  clause  *4-221 
Record  buffer 

DATA  pointers  *  4-270 

MAP  DYNAMIC  pointers  *  4-160,  4-266 

moving  data  *4-184 

REMAP  pointers  *4-264,  4-266 

setting  size  *4-2 15 

RECORD  clause  *4-89,  4-110,  4-245,  4-246 
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Record  file  address  (RFA)*  1-14,  4-89,  4-110, 
4-114 

Record  Management  Services 
See  RMS 
Record  pointers 

after  FIND  statement  •  4-90,  4-9 1 
after  GET  statement  *4-111,  4-112 
after  PUT  statement  •  4-246 
after  UPDATE  statement  •  4-324 
REMAP  statement  •  4-266 
RESTORE  statement  •  4-270 
WINDOWSIZE  clause  *4-222 
Records 

deleting  with  DELETE  statement  *  4-56 
deleting  with  SCRATCH  statement  *  4-280 
finding  RFA  of  *4-89,  4-110 
locating  by  KEY  *  4-9 1,4-110,4-112 
locating  by  RECORD  number  *4-1 10 
locating  by  RFA  *  4-89,  4-9 1,4-110,4-112 
locating  randomly  *  4-9 1 
locating  sequentially  *4-89,  4-91,  4-110, 
4-112 

locating  with  FIND  statement  *  4-88 
locating  with  GET  statement  *4- 109 
locking  *4-1 12 
processing  *4-109,  4-2 1 6 
retrieving  by  KEY  *4-1 10,  4-1 12 
retrieving  by  RECORD  number  *4-1 10 
retrieving  by  RFA  *  4- 1 1 0,  4- 1 1 2 
retrieving  randomly  *4-1 12 
retrieving  sequentially  *4-1 10,  4-1 12 
retrieving  with  GET  statement  *4- 109 
size  of  *  4-245 
stream  *  4-2 1 9 
unlocking  *  4-56,  4-112 
unlocking  with  UNLOCK  statement  *  4-320 
writing  by  RECORD  number  *4-245 
writing  sequentially  *  4-246 
writing  with  PRINT  statement  *  4-232 
writing  with  PUT  statement  *  4-245 
writing  with  UPDATE  statement  *  4-324 
RECORDSIZE  clause  *4- 158,  4-221,  4-245 
RECORDTYPE  clause  *4-221 
RECOUNT  debugger  command* B- 16,  B-17 
RECOUNT  function  *  4-260  to  4-26 1 
after  GET  statement  *4-1 12 
after  INPUT  LINE  statement  *4- 127 


RECOUNT  function  (cont'd.) 
after  INPUT  statement  *4- 124 
after  LINPUT  statement  *  4- 1 43 
Recursion 

in  DEF*  functions  *  4-54 
In  DEF  functions  *  4-49 
in  error  handlers  *4-201 
Redimensioning  arrays 

with  executable  DIM  statement  *  4-64 
REDIRECT  debugger  command* B-17,  B-18 
Relational  expressions*  1-41 

compared  with  logical*  1-45,  1-46 
definition  of*  1-40 
format  of  *  1  -4 1 

in  SELECT  statement  *  4-284,  4-285 
numeric*  1-41 
string  *  1-42 
truth  tests*  1-41,  1-42 
Relational  operators 
numeric*  1-41 
string*  1-43 
Relative  files  *  4-2 1 9 

BUCKETSIZE  clause  *  4-2 1 5 
deleting  records  in  *  4-56 
finding  records  in  *4-91 
opening  *4-2 18 
record  size  In  *  4-222 
retrieving  records  sequentially  in  *4-1 12 
updating  *4-325 
writing  records  to  *  4-246 
REMAP  statement  *  4-264  to  4-268 
FILL  keywords  *  4-26 
with  MAP  DYNAMIC  statement  *4- 160 
REM  statement  *  4-262  to  4-263 
in  multi-statement  lines*  1-8 
multi-line  format*  1-11,  4-262 
terminating*  1-11,  4-262 
transferring  control  to*  1-1 1 
RENAME  command  *2-50  to  2-51 
REPLACE  command  *2-52  to  2-53 
with  RENAME  command  *2-50 
Reserved  words  *  1  -4 
RESET  statement  *4-269,  4-270 
See  also  RESTORE  statement 
RESTORE  statement  *4-270  to  4-271 
Result  data  types 

mixed-mode  expressions*  1-39 
RESUME  statement  *4-272  to  4-273 
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RESUME  statement  (cont'd.) 

END  statement  •4-72 
ERL  function  *4-74 
ERN$  function  •  4-75 
ERR  function  *4-76 
INPUT  LINE  statement  *4- 127 
INPUT  statement  *4- 124 
LINPUT  statement  *4- 143 
RETURN  statement  *4-274 
RFA 

See  Record  file  address 
RFA  clause  •4-89,  4-110 
RFA  data  type 

allowable  operations*  1-14 
R  formatting  character 

in  PRINT  USING  statement  •  4-240 
RIGHTS  function  *4-275  to  4-276 
See  also  SEGS  function 
Right-justification 

PRINT  USING  statement  *4-240 
with  RSET  statement  *4-279 
RMS 

accessing  records  *4- 109 
deleting  records  *  4-56 
library  file  *  2-46 
library  names* 2-55 
locating  records  *  4-87 
memory-resident  library  *  2-53 
opening  files  *4-21 1 
overlay  structure  *  2-44 
replacing  records  *  4-324 
RMSRES  command  *  2-53 
RND  function  *4-277  to  4-278 
See  also  RANDOMIZE  statement 
RSET  statement  *4-279 
RUN  command  *2-57  to  2-62 
/BYTE  qualfier*2-59 
/DOUBLE  qualifier  *2-59 
/LONG  qualifier  *2-60 
/[NOjCHAIN  qualfier*  2-59 
/[NOJDEBUG  qualfier  *2-59 
/[NO]FLAG  qualifier  *2-60 
/[NOJLINE  qualifier  *2-60 
/[NojsCALE  qualifier  *2-60 
/[NojsYNT  AX -CHECK  qualifier  *  2-61 
/SINGLE  qualifier  *2-61 
STOP  statement  *  2-58 


RUN  command  (cont'd.) 

/TYPE-DEFAULT  qualifier*  2-61 
/VARIANT  qualifier  *2-61 
/WORD  qualifier* 2-61 


s 


SAVE  command  *  2-63  to  2-64 
with  RENAME  command  *  2-50 
%SBTTL  directive  *3- 18,  3-19 
SCALE  command  *  2-65  to  2-66 
Scale  factor  *2-60,  2-65 

setting  with  OPTION  statement  *  4-225 
setting  with  SCALE  command  *  2-65 
SCRATCH  command  *2-67 
SCRATCH  statement  *4-280 
SEGS  function  *4-281  to  4-282 
Segmented  keys  *  4-220 
SELECT  block  *4-205,  4-207,  4-283 
SELECT  statement  *4-283  to  4-285 
Semicolon  (;) 

in  INPUT  LINE  statement* 4-127 
in  INPUT  statement  *4- 123 
in  LINPUT  statement  *  4- 1 43 
In  MAT  PRINT  statement  *4-171 
in  PRINT  statement  *  4-232 
SEQUENCE  command  *  2-68  to  2-69 
Sequential  files  *  4-2 1 9 

deleting  records  In  *  4-280 
finding  records  in  *4-91 
fixed-length  *4-2 19 
[NOJSPAN  clause  *4-2 18 
opening  *  4-2 1 8 
record  size  in  *  4-222 
retrieving  records  in  *  4-1 1 2 
stream  *4-2 19 
updating  *  4-325 
variable-length  *  4-2 1 9 
writing  records  to  *4-232,  4-246 
SET  [NO]  PROMPT  statement  *  4-286  to  4-287 
SET  command  *  2-70  to  2-77 
/BYTE  qualfier  *2-71 
defaults  *  2-70 
/DOUBLE  qualifier  *2-73 
/EXTEND  qualifier  *2-73 
/LONG  qualifier  *2-75 
/[NOjCHAIN  qualfier  *2-71 
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SET  command  (cont'd.) 

/[NO]CLUSTER  qualfier*  2-72 
/[NO]CROSS_REFERENCE  qualifier* 2-72 
/[NOJDEBUG  qualfier*2-72 
/[NOPUMP  qualifier  *2-73 
/[NOJFLAG  qualifier  *2-73 
/[NojlDS  qualifier* 2-74 
/[NO]INDEX  qualifier  *2-74 
/[NOjllNE  qualifier* 2-74 
/[NojllST  qualifier* 2-74 
/[NO]MACRO  qualifier  *2-75 
/[NOJOBJECT  qualifier  *2-75 
/[NO]RELATIVE  qualifier  *  2-75 
/[NO]SEQUENTIAL  qualifier  *  2-75 
/[NO]SYNTAX -CHECK  qualifier  *  2-76 
/[NO]VIRTUAL  qualifier  *2-76 
/[NOJWARNINGS  qualifier* 2-77 
/PAGE-SIZE  qualifier  *2-75 
/SINGLE  qualifier* 2-76 
/TYPE_DEFAULT  qualifier*  1-16,  2-76 
/VARIANT  qualifier  *2-76,  3-22 
/WIDTH  qualifier  *2-77 
/WORD  qualifier* 2-77 
SGN  function  *  4-288 
SHOW  command  *2-78  to  2-79 
defaults  *2-78 
Sine  *4-289 
SIN  function  *  4-289 
SINGLE  data  type*  1-13 
Single-line 

DEF*  functions  *4-52 
DEF  statement  *  4-47 
loops  *4-96,  4-322,  4-330 
Single-statement  lines*  1-5 
Size 

of  numeric  data*  1-14 
of  STRING  data*  1-13 
SLEEP  statement  *  4-290 
Source  text 
copying*  1-8 
SPACES  function  *4-291 
SQR  function  *  4-292 
SORT  function  *  4-292 
Square  root  *  4-292 
Statement 

backslash  separator*  1-6 

block  *4-71,  4-79,  4-97,  4-119,  4-285 

components  of*  1-3 


Statement  (cont'd.) 
continued*  1-5,  1-6 
data  typing*  1-17 
declarative  *  4-42 
empty*  1-10 
executable*  1-3 
execution  of*  1-6,  B-20 
format  of  *  1  -3 
labeling  of*  1-2 
multi-statement  lines*  1-6 
nonexecutable*  1-3,  1-12,  4-28,  4-39,  4-44, 
4-63,  4-84,  4-157,  4-160,  4-262 
order  of  *  1-12 
processing  of*  1-12 
single-line*  1-5 
Statement  blocks 
ending  *4-71 
exiting  *  4-78 
Statement  modifiers 
FOR  statement  *  4-96 
IF  statement  *4-1 19 
UNLESS  statement  *  4-3 1 9 
UNTIL  statement  *  4-323 
WHILE  statement  *  4-33 1 
Statements 
CALL  *4-8 

CAUSE  ERROR  *4- 14  > 

CHAIN  *4- 17 
CHANGE  *4- 19 
CLOSE  *4-23 
COMMON  *4-25 
DATA  *  4-38 
DECLARE  *4-42 
DEF  *4-46 
DEF*  *4-51 
DELETE  *4-56 
DIMENSION  *4-62 
END  *4-71 
EXIT  *4-78 
EXTERNAL  *4-82 
FIELD  *4-86 
FIND  *4-88 
FNEND*4-94 
FNEXIT*4-95 
FOR  *4-96 
FUNCTION  *4- 104 
FUNCTIONEND*4-107 
FUNCTIONEXIT*4^108 
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Statements  (cont'd.) 

GET  *4- 109 

G0SUB«4-116 

GOTO«4-118 

IF...THEN...ELSE®4-119 

INPUT  •4- 122 

INPUT  LINE  *4- 126 

ITERATE  *4- 135 

KILL  *4- 136 

LET  *4- 140 

LINPUT*4-142 

LSET®4-149 

MAP  *4- 156 

MAP  DYNAMIC  *4- 159 

MAT  •4- 162 

MAT  INPUT  *4- 166 

MAT  LINPUT«4-168 

MAT  PRINT  *4-1 71 

MAT  READ  •A- 174 

MOVE  *4- 184 

NAME...AS«4-188 

NEXT  *4- 190 

ON...GOSUB*  4-205 

ON...GOTO*  4-207 

ON  ERROR  GO  BACK  *4- 199 

ON  ERROR  GOTO  *4-201 

ON  ERROR  GOTO  0*4-203 

OPEN  *4-2 11 

OPTION  *4-224 

PRINT  *4-232 

PRINT  USING  *4-236 

PROGRAM  *4-244 

PUT  *4-245 

RANDOMIZE  *4-252 

READ  *4-256 

REM  *4-262 

REMAP  *4-264 

RESET  *4-269 

RESTORE  *4-270 

RESUME  *4-272 

RETURN  *4-274 

RSET*  4-279 

SCRATCH  *4-280 

SELECT  *4-283 

SET  [NO]  PROMPT  *4-286 

SLEEP  *4-290 

STOP  *4-296 

SUB  *4-302 


Statements  (cont'd.) 

SUBEND  *4-305 
SUBEXIT  *4-306 
UNLESS  *4-3 19 
UNLOCK  *4-320 
UNTIL  *4-322 
UPDATE  *  4-324 
WAIT  *4-328 
WHILE  *4-330 
Static 

mapping  *4- 156 
storage  *  4-26,  4-156,  4-266 
STATUS  debugger  command  *  B- 18,  B-20 
STATUS  function  *4-293  to  4-295 
STEP  clause  *  4-97 

STEP  debugger  command  *  B-20,  B-22 
STOP  statement  *  4-296  to  4-297 

See  also  CONTINUE  debugger  command 
debugger  control  *  4-296 
line  number* 4-296 
module  name  *4-296 
number  sign  (#)  prompt  *  4-296 
resuming  execution  *  4-296 
Storage 

allocating  with  MAP  DYNAMIC  statement* 
4-159 

allocating  with  MAP  statement  *4- 157 
allocating  with  REMAP  statement  *  4-264 
COMMON  area  and  MAP  area  *4-28,  4-158 
dynamic  *4- 159,  4-264,  4-266 
FILL  keywords  *  4-26,  4-185,  4-265 
for  arrays  *  4-64 
in  COMMON  statement  *  4-29 
in  MAP  statement* 4-158 
of  data  *  1  - 1 4 
of  RFA  data  *1-14 
of  STRING  data*  1-13 
shared  *4-25,  4-156 
static  *4-26,  4-156,  4-266 
STR$  function  *  4-298  to  4-299 
Stream 

record  format  *  4-2 1 9 
STRINGS  function  *4-300  to  4-301 
String  arithmetic  functions 
DIFS  function  *  4-60 
PLACES  function  *4-227 
PRODS  function  *  4-242 
OUOS  function  *  4-249 
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String  arithmetic  functions  (cont'd.) 

SUMS  function  •  4-307 
String  constant*  1-28 
String  data 

assigning  with  LSET  statement  *4- 149 
assigning  with  RSET  statement  *4-279 
STRING  data  type*  1-13 
length*  1-14 
storage  of  *  1  - 1 3 

STRING  debugger  command  *B-22,  B-23 
String  expressions*  1-40 
relational*  1-42 
String  functions  *  4-35 
ASCII  function  *  4-5 
EDITS  function  *  4-69 
INSTR  function  *4-129 
LEFTS  function  *4-137 
LEN  function  *4- 139 
MIDS  function  *4-178 
POS  function  *  4-230 
RIGHTS  function  *4-275 
SEGS  function  *  4-28 1 
SPACES  function  *  4-29 1 
STRINGS  function  *  4-300 
TRMS  function  *  4-3 1 8 
XLATES  function  *  4-332 
String  literal 
numeric*  1-32 
String  literals*  1-44 
continuing*  1-6 
delimiter*  1-28 
in  PRINT  statement  *  4-233 
in  PRINT  USING  statement  *  4-240 
processing  of  *  1-12 
quotation  marks  in*  1-28 
String  relational  expressions 
evaluation  of*  1-42 
operators  *  1  -43 
padding*  1-42 
Strings 

See  also  Substrings 
comparing*  1-42,  4-30 
concatenating*  1-6,  1-37,  1-40 
converting  *4- 19 
creating  *  4-29 1 ,  4-300 
editing  *4-69,  4-318 

extracting  substrings  *4- 137,  4-178,  4-275, 
4-281 


Strings  (cont'd.) 

finding  length  *4- 139 
finding  substrings  *4- 129,  4-230 
justifying  with  FORMATS  function  *  4-100 
justifying  with  LSET  statement* 4-149 
justifying  with  PRINT  USING  statement  *  4-240 
justifying  with  RSET  statement* 4-279 
numeric  *4-30,  4-60,  4-133,  4-227,  4-242, 
4-249,  4-258,  4-307,  4-326,  4-327 
replacing  substrings  *4- 178 
storage  of  *B-22 
suffix  character*  1-16 
String  variables*  1-20 

formatting  storage  *4- 149,  4-279 
in  INPUT  LINE  statement  *4- 127 
in  INPUT  statement  *4- 123 
in  LET  statement  *4- 140 
in  LINPUT  statement  *  4- 1 43 
SUBEND  statement  *  4-305 
See  also  END  statement 
SUBEXIT  statement  *  4-306 
See  also  EXIT  statement 
Subprogram 
calling  *4-8 
declaring  *  4-82 
ending  *4-71,  4-105 

error  handling  In  *4-72,  4-79,  4-105,  4-199 
exiting  *4-78 

FUNCTION  statement  *4-104 
naming  *  4-8 
Subprograms 
creating  *  4-302 
ending  *  4-303 
naming  *  4-302 
returning  from  *  4-274 
SUB  statement  *  4-302 
Subroutines 
external  *  4-83 
GOSUB  statement  *4-1 16 
RETURN  statement  *4-274 
Subscripted  variables*  1-21 
format  of  *  1  -22 
subscript  range*  1-21 
Subscripts*  1-21 
range  of  *  1-21 

SUB  statement  *  4-302  to  4-304 
parameter  *  4-302 

parameter-passing  mechanisms  *  4-9  to  4-10t 
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SUBSTITUTE  editing  mode  command  •  C-9 
Substrings 

extracting  *4- 178,  4-281 
extracting  with  LEFTS  function  *  4- 137 
extracting  with  MID$  function  *  4- 178 
extracting  with  RIGHTS  function  *4-275 
extracting  with  SEGS  function  •  4-28 1 
finding  *4- 129,  4-230 
replacing  *4-1 78 
Suffix  character 

dollar  sign  (S)  •  1-16 
percent  sign  (%)•  1-16 
SUMS  function  •  4-307  to  4-308 
SWAP%  function  •  4-309 
SYS  function  •  4-310 
S  system-command  •  2-2  to  2-3 


T 


TAB  function  •4-311  to  4-3 1 2 
T AN  function  •  4-3 1 3 
Tangent*  4-313 
Task 

overlaying  *  4-28 
Task  Builder 

command  file  *  2-9 
library  *  2-6 

object  module  library  *  2-24 
ODL  file  *2-9 

TEMPORARY  clause  *4-222 

Tensor*  1-22 

Terminal 

printing  to  *  4-232 
Terminal  control  functions 
ECHO  function  *  4-67 
NOECHO  function  *4- 192 
RCTRLO  function  *  4-254 
TAB  function  *  4-3 1 1 
Terminal-format  files  *4-221,  4-222 

Input  from  *4- 122,  4-126,  4-142,  4-166, 
4-168 

writing  records  to  *  4- 1 7 1 ,  4-232 
TIMES  function  *  4-3 1 6  to  4-3 1 7 
TIME  function  *  4-3 1 4  to  4-3 1 5t 
function  values  *  4-3 1 4  to  4-3 1 5t 
%TITLE  directive  *3-20,  3-21 
TRACE  debugger  command  *B-23,  B-25 


Trailing  minus  sign  field 

In  PRINT  USING  statement  *4-237 
Trigonometric  functions 
ATN  function  *  4-6 
COS  function  *  4-3 1 
SIN  function  *  4-289 
T AN  function  *  4-3 1 3 
TRMS  function  *  4-3 1 8 
TRN  keyword  *4- 165 
Truncation 

In  numeric  strings  *4-227,  4-228  to  4-229t, 
4-242,  4-249 

in  PRINT  USING  statement  *  4-240 
with  FIX  function  *  4-93 
Truth  tables*  1-46 
Truth  tests 

in  logical  expressions*  1-46 
In  relational  expressions*  1-41 
in  string  relational  expressions*  1-42 


u 


UNBREAK  debugger  command  *  B-25,  B-27 
Unconditional  branching 

with  GOSUB  statement  *4-1 16 
with  GOTO  statement  *4-1 18 
Unconditional  loop  *4-97 
Underscore  (_) 

In  PRINT  USING  statement  *  4-238 
In  variable  names*  1-19 
UNLESS  statement  *  4-3 1 9 
UNLOCK  statement  *4-320  to  4-321 
UNSAVE  command  *2-80 
UNTIL  clause  *4-98 
UNTIL  loops  *4- 190 

error  handling  in  *4-273 
exiting  *4-79 

explicit  Iteration  of  *4- 135 
transferring  control  Into  *4-1 16,  4-118,  4-205, 
4-207 

UNTIL  statement  *  4-322  to  4-323 
UNTRACE  debugger  command  *  B-27,  B-28 
UPDATE  statement  *  4-324  to  4-325 
with  UNLOCK  statement  *  4-320 
Uppercase  letters 

In  EDIT  command  *2-27 
in  PRINT  USING  statement  *  4-240 
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Uppercase  letters  (cont'd.) 

processing  of*  1-12 
User-defined  functions  •  4-46,  4-51 
USEROPEN  clause  •  4-222 


V 


VAL%  function  *4-327 
VAL  function  *  4-326 
Values 

assigning  to  array  elements  *4- 164,  4-166, 
4-168,  4-174,  4-256 
assigning  to  variables  *4- 140 
assigning  with  LET  statement  *  4- 1 40 
assigning  with  LINPUT  statement  *4- 142 
assigning  with  LSET  statement  *4- 149 
assigning  with  MAT  INPUT  statement  *4- 166 
assigning  with  MAT  LINPUT  statement  *4- 168 
assigning  with  MAT  READ  statement  *  4- 1 74 
assigning  with  READ  statement  *4-256 
assigning  with  RSET  statement  *  4-279 
comparing  *  4-89 
Variable  names 
assigning*  1-18 
In  COMMON  statement  *  4-29 
In  MAP  DYNAMIC  statement  *4- 160 
In  MAP  statement  *4- 157 
in  REMAP  statement  *  4-265 
Variables*  1-18 

assigning  values  to  *4- 122,  4-126,  4-140, 
4-142,  4-256 
changing  values  *B- 13 
comparing  *  4-89 
declaring  *  4-42 
definition  of  *  1-18 
displaying  during  debugging* B- 15 
explicitly  declared*  1-20 
external  *  4-83 
floating-point*  1-19 
Implicitly  declared*  1-19 
initialization  of*  1-23,  4-29,  4-44 
in  MOVE  statement  *4- 184 
In  SUB  subprograms  *  4-303 
integer*  1-20 
loop  *  4-97 
naming*  1-18 

string*  1-20,  4-123,  4-127,  4-140,  4-143 


Variables  (cont'd.) 

subscripted*  1-21 
%VARIANT  directive  *3-22,  3-23 
in  %IF  directive  *  3-6 
in  %LET  directive  *3- 10 
/VARIANT  qualifier  *3-22 
Vector*  1-22 
Version  identification  *  3-4 
Virtual  array  *4-62,  4-64 
declaring  *  4-44 
initialization  of  *4-65 
LSET  statement  *4- 149 
padding  in  *  4-64 
RSET  statement  *  4-279 
Virtual  arrays 

initialization  of*  1-23 
Virtual  file  *  4-2 1 9 
record  size  *  4-222 
with  RESTORE  statement  *  4-27 1 


w 


WAIT  statement  *  4-328  to  4-329 
WHILE  clause  *4-98 
WHILE  loops  *4- 190 
error  handling  In  *4-273 
exiting  *4-79 

explicit  iteration  of  *4- 135 
transferring  control  Into  *4-1 16,  4-1 18,  4-205, 
4-207 

WHILE  statement  *  4-330  to  4-331 
WINDOWSIZE  clause  *4-222 
WORD  data  type*  1-13 


X 


XLATE$  function  *4-332  to  4-333 


z 


ZER  keyword  *4-164 
Zero 

array  element*  1-22,  4-64,  4-163,  4-167, 
4-169,  4-172,  4-175,  4-186 
blank-if-zero  field  *  4-238 
fill  field  in  PRINT  USING  statement  *  4-238 


Index-25 


BASIC-PLUS-2  Reference  Manual 
AA-JP30A-TK 


READER'S 
COMMENTS 


ni?iTAy^'®  comments  only. 

DIGITAL  will  use  comments  submitted  on  this  form 

at  the  company's  discretion.  If  you  require  a  written 
re(^y  and  are  eligible  to  receive  one  under  Software 
Performance  Report  (SPR)  service,  submit  your 
comments  on  an  SPR  form. 


Plesse  indicate  the  type  of  user/readet  that  you  most  neady  represent: 


□  Assembly  language  programmer 

□  Higher-level  language  programmer 

U  Occasional  programmer  (experienced) 

U  User  with  little  programming  experience 
U  Student  programmer 

□  Other  (please  specify)  _ _ 


Name 


-  Date  . 


Organization 
Street 
City _ 


.  State  . 


-  Zip  Code  _ 
or  Country 


_ Do  Not  Tear-Fold  Here  and  Tape 


SDIlDaSD 


No  Postage 
Necessary 
if  Mailed 
in  the 

United  States 


business  reply  mail 

first  class  permit  no.  33  MAYNARD  MASS. 

POSTAGE  WILL  BE  PAID  BY  ADDRESSEE 


digital  equipment  corporation 

The  Manager,  Office  Program 
ZK02-1/N20 

110  SPIT  BROOK  ROAD 
NASHUA,  NH  03062  -  9990 


I 

I 

I 

I 

-I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 


Do  Not  Tear-Fold  Here  ---- 


I 

I 


Cut  Along  Dotted  Line 


BASIC-PLUS-2  Reference  Manual 
AA-JP30A-TK 


READER'S  Note:  This  form  is  for  document  comments  only. 

COMMENTS  digital  will  use  comments  submitted  on  this  form 

at  the  company's  discretion.  If  you  require  a  written 
reply  and  are  eligible  to  receive  one  under  Software 
Performance  Report  (SPR)  service,  submit  your 
comments  on  an  SPR  form. 

Did  you  find  this  manual  understandable,  usable,  and  well  organized?  Please  make 
suggestions  for  improvement. 


Did  you  find  errors  in  this  manual?  If  so,  specify  the  error  and  the  page  number. 


Please  indicate  the  type  of  user/reader  that  you  most  nearly  represent: 

□  Assembly  language  programmer 

□  Higher-level  language  programmer 

□  Occasional  programmer  (experienced) 

□  User  with  little  programming  experience 

□  Student  programmer 

□  Other  (please  specify)  _ _ _ 

Name - - Date _ 

Organization  _  _ _ _ _ _ 

Street _ _ _ 

- -  State _ Zip  Code  . 

or  Country 


---Do  Not  Tear-Fold  Here  and  Tape 


BSD 


BUSINESS  REPLY  MAIL 

FIRST  CLASS  PERMIT  NO.  33  MAYNARD  MASS. 
POSTAGE  WILL  BE  PAID  BY  ADDRESSEE 


DIGITAL  EQUIPMENT  CORPORATION 
The  Manager,  Office  Program 
ZK02-1/N20 

110  SPIT  BROOK  ROAD 
NASHUA,  NH  03062  -  9990 


No  Postage 
Necessary 
if  Mailed 
in  the 

United  States 


■---  Do  Not  Tear-Fold  Here 


liiiililliliililiililiilliliiili 


Cut  Along  Dotted  Line 


